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Preface 


The Programmer’s Guide: CTIX Supplement discusses in detail various 
tools provided with the CTIX* operating system. This manual should 
be used in conjunction with the C7/X Operating System Manual, which 
is a more general and comprehensive reference on the CTIX operat- 
ing system. The Programmer's Guide: UNIX System V should be 
used as a reference on tools such as awk, make, the C programming 
language, Common Object File Format, and so forth. 


The tools described in this manual address four areas: 


e Support Tools: the m4 macro processor; and the calculator 
programs bc and dc. 


e Text Editing: display editing with vi; and sed, a non- 
interactive text editor. 


e Text Formatting: an nroff/troff user's guide and _ tutorial; 
preparing documents with the macro packages -me, -mm and 
-me, typesetting mathematics with eqn; and tbl, a program to 
format tables. 


e CTIX Programming: Convergent Technologies S/1280 Inter- 
CPU communication facility; and the CTIX system assembler 
user’s guide, 


The first three parts of this manual (Chapters 1 to 13) consist of stan- 
dard documentation released by AT&T that describes the UNIX 
Operating System or documentation originating from the University 


* 


A trademark of Convergent Technologies, Inc. The CTIX operating system is 
derived from UNIX System V by Convergent Technologies under license from 
AT&T. UNIX is a trademark of AT&T Bell Laboratories. 
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of California, Berkeley. Due to the ‘‘classical’’ nature of these docu- 
ments, their contents have not been altered with the exception of 
minor formatting changes needed to conform to CTIX manual style. 
In order to keep as true to the original documents as possible, the 
conventions vary from chapter to chapter; in addition, because this 
manual is published in a reduced format, point sizes mentioned in 
articles are not true to scale. Many of the articles refer to other 
operating systems, such as GCOS, and other hardware, such as PDP- 
11. In all cases, however, the documentation is compatible with the 
CTIX operating system. 
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The M4 Macro Processor 


Abstract 


M4 is a macro processor available on UNIX and GCOS. Its primary 
use has been as a front end for Ratfor for those cases where parame- 
terless macros are not adequately powerful. It has also been used for 
languages as disparate as C and Cobol. M4 is particularly suited for 
functional languages like Fortran, PL/I and C since macros are speci- 
fied in a functional notation. 


M64 provides features seldom found even in much larger macro pro- 
cessors, including 


e arguments 

® condition testing 

e arithmetic capabilities 

® string and substring functions 
e file manipulation 


This paper is a user’s manual for M4. 


Source: Brian W. Kernighan and Dennis M. Ritchie, The M4 Macro Processor 
(Murray Hill, N.J.: Bell Laboratories, 1977). 
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Introduction 


A macro processor is a useful way to enhance a programming 
language, to make it more palatable or more readable, or to tailor it 
to a particular application. The #define statement in C and the 
analogous define in Ratfor are examples of the basic facility provided 
by any macro processor—replacement of text by other text. 


The M4 macro processor is an extension of a macro processor called 
M3 which was written by D. M. Ritchie for the AP-3 minicomputer; 
M3 was in turn based on a macro processor implemented for [1]. 
Readers unfamiliar with the basic ideas of macro processing may wish 
to read some of the discussion there. 


M4 is a suitable front end for Ratfor and C, and has also been used 
successfully with Cobol. Besides the straightforward replacement of 
one string of text by another, it provides macros with arguments, con- 
ditional macro expansion, arithmetic, file manipulation, and some 
specialized string processing functions. 


The basic operation of M4 is to copy its input to its output. As the 
input is read, however, each alphanumeric ‘‘token”’ (that is, string of 
letters and digits) is checked. If it is the name of a macro, then the 
name of the macro is replaced by its defining text, and the resulting 
string is pushed back onto the input to be rescanned. Macros may be 
called with arguments, in which case the arguments are collected and 
substituted into the right places in the defining text before it is res- 
canned. 


M4 provides a collection of about twenty built-in macros which per- 
form various useful operations; in addition, the user can define new 
macros. Built-ins and user-defined macros work exactly the same 
way, except that some of the built-in macros have side effects on the 
state of the process. 


Usage 


On UNIX, use 
m4 [files] 


Each argument file is processed in order; if there are no arguments, 
or if an argument is ‘—’, the standard input is read at that point. The 
processed text is written on the standard output, which may be 
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captured for subsequent processing with 
m4 [files] >outputfile 
On GCOS, usage is identical, but the program is called ./m4 . 


Defining Macros 


The primary built-in function of M4 is define, which is used to define 
new macros. The input 


define(name, stuff) 


causes the string name to be defined as stuff. All subsequent 
occurrences of name will be replaced by stuff. mame must be 
alphanumeric and must begin with a letter (the underscore _ counts as 
a letter). stuff is any text that contains balanced parentheses, it may 
stretch over multiple lines. 


Thus, as a typical example, 

define(N, 100) 

if (i > N) 
defines N to be 100, and uses this ‘‘symbolic constant” in a later if 
statement. 


The left parenthesis must immediately follow the word define, to sig- 
nal that define has arguments. If a macro or built-in name is not fol- 
lowed immediately by ‘(’, it is assumed to have no arguments. This is 
the situation for N above; it is actually a macro with no arguments, 
and thus when it is used there need be no (...) following it. 


You should also notice that a macro name is only recognized as such 
if it appears surrounded by non-alphanumerics. For example, in 


define(N, 100) 


if (NNN > 100) 


the variable NNN is absolutely unrelated to the defined macro N, 
even though it contains a lot of N’s. 


Things may be defined in terms of other things. For example, 
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define(N, 100) 
define(M, N) 


defines both M and N to be 100. 


What happens if N is redefined? Or, to say it another way, is M 
defined as N or as 100? In M4, the latter is true—M is 100, so even 
if N subsequently changes, M does not. 


This behavior arises because M4 expands macro names into their 
defining text as soon as it possibly can. Here, that means that when 
the string N is seen as the arguments of define are being collected, it 
is immediately replaced by 100; it’s just as if you had said 


define(M, 100) 
in the first place. 


If this isn’t what you really want, there are two ways out of it. The 
first, which is specific to this situation, is to interchange the order of 
the definitions: 


define(M, N) 
define(N, 100) 


Now M is defined to be the string N, so when you ask for M later, 
you'll always get the value of N at that time (because the M will be 
replaced by N which will be replaced by 100). 


Quoting 


The more general solution is to delay the expansion of the arguments 
of define by quoting them. Any text surrounded by the single quotes 
~ and * is not expanded immediately, but has the quotes stripped off. 
If you say 


define(N, 100) 
define(M, ‘N’) 


the quotes around the N are stripped off as the argument is being col- 
lected, but they have served their purpose, and M is defined as the 
string N, not 100. The general rule is that M4 always strips off one 
level of single quotes whenever it evaluates something. This is true 
even outside of macros. If you want the word define to appear in the 
output, you have to quote it in the input, as in 


‘define’ = 1; 


I—4 Programmer's Guide: CTIX Supplement 


As another instance of the same thing, which is a bit more surprising, 
consider redefining N: 


define(N, 100) 


define(N, 200) 


Perhaps regrettably, the N in the second definition is evaluated as 
soon as it’s seen; that is, it is replaced by 100, so it’s as if you had 
written 


define(100, 200) 


This statement is ignored by M4, since you can only define things 
that look like names, but it obviously doesn’t have the effect you 
wanted. To really redefine N, you must delay the evaluation by quot- 


ing: 
define(N, 100) 


define(‘N’, 200) 
In M4, it is often wise to quote the first argument of a macro. 


If ~ and ~ are not convenient for some reason, the quote characters 
can be changed with the built-in changequote: 


changequote([, ]) 


makes the new quote characters the left and right brackets. You can 
restore the original characters with just 


changequote 
There are two additional built-ins related to define. undefine 
removes the definition of some macro or built-in: 

undefine(‘N’) 


removes the definition of N. (Why are the quotes absolutely neces- 
sary?) Built-ins can be removed with undefine, as in 


undefine(‘define’) 
but once you remove one, you can never get it back. 


The built-in ifdef provides a way to determine if a macro is currently 
defined. In particular, M4 has pre-defined the names unix and gcos 
on the corresponding systems, so you can tell which one you’re using: 


The M4 Macro Processor 1—S5 


ifdef(‘unix’, ‘define(wordsize,16)’ ) 
ifdef(‘gcos’, ‘define(wordsize,36)’ ) 


makes a definition appropriate for the particular machine. Don’t for- 
get the quotes! 


ifdef actually permits three arguments; if the name is undefined, the 
value of ifdef is then the third argument, as in 


ifdef(‘unix’, on UNIX, not on UNIX) 


Arguments 


So far we have discussed the simplest form of macro processing-— 
replacing one string by another (fixed) string. User-defined macros 
may also have arguments, so different invocations can have different 
results. Within the replacement text for a macro (the second argu- 
ment of its define) any occurrence of $n will be replaced by the nth 
argument when the macro is actually used. Thus, the macro bump, 
defined as 


define(bump, $1 = $1 + 1) 
generates code to increment its argument by 1: 


bump(x) 


x=x+1 


A macro can have as many arguments as you want, but only the first 
nine are accessible, through $1 to $9. (The macro name itself is $0, 
although that is less commonly used.) Arguments that are not sup- 
plied are replaced by null strings, so we can define a macro cat which 
simply concatenates its arguments, like this: 


define(cat, $1$2$3$4$5$6$7$8$9) 
Thus 

cat(x, y, Z) 
is equivalent to 


XYZ 
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$4 through $9 are null, since no corresponding arguments were pro- 
vided. 


Leading unquoted blanks, tabs, or newlines that occur during argu- 
ment collection are discarded. All other white space is retained. 
Thus 


define(a, b= c) 
defines ato beb c. 


Arguments are separated by commas, but parentheses are counted 
properly, so a comma “‘protected’”’ by parentheses does not terminate 
an argument. That is, in 


define(a, (b,c)) 


there are only two arguments; the second is literally (b,c). And of 
course a bare comma or parenthesis can be inserted by quoting it. 


Arithmetic Built-ins 


M4 provides two built-in functions for doing arithmetic on integers 
(only). The simplest is iner, which increments its numeric argument 
by 1. Thus to handle the common programming situation where you 
want a variable to be defined as ‘‘one more than N”’, write 


define(N, 100) 
define(N1, ‘incr(N)’) 


Then NI is defined as one more than the current value of N. 


The more general mechanism for arithmetic is a built-in called eval, 
which is capable of arbitrary arithmetic on integers. It provides the 
operators (in decreasing order of precedence) 


unary + and — 

MOL > (exponentiation) 
* / %(modulus) 

in Cs 

aa lS <-<= > = 

! (not) 

& or && (logical and) 

| or II (logical or) 


Parentheses may be used to group operations where needed. All the 
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operands of an expression given to eval must ultimately be numeric. 
The numeric value of a true relation (like 1>0) is 1, and false is 0. 
The precision in eval is 32 bits on UNIX and 36 bits on GCOS. 


As a simple example, suppose we want M to be 2**N+1. Then 


define(N, 3) 
define(M, ‘eval(2**N+1)’) 


As a matter of principle, it is advisable to quote the defining text for 
a macro unless it is very simple indeed (say just a number); it usually 
gives the result you want, and is a good habit to get into. 


File Manipulation 


You can include a new file in the input at any time by the built-in 
function include: 


include(filename) 


inserts the contents of filename in place of the include command. 
The contents of the file is often a set of definitions. The value of 
include (that is, its replacement text) is the contents of the file; this 
can be captured in definitions, etc. 


It is a fatal error if the file named in include cannot be accessed. To 
get some control over this situation, the alternate form sinclude can 
be used; sinclude (‘silent include’’) says nothing and continues if it 
can’t access the file. 


It is also possible to divert the output of M4 to temporary files during 
processing, and output the collected material upon command. M4 
maintains nine of these diversions, numbered 1 through 9. If you say 


divert(n) 


all subsequent output is put onto the end of a temporary file referred 
to asn. Diverting to this file is stopped by another divert command; 
in particular, divert or divert(0) resumes the normal output process. 


Diverted text is normally output all at once at the end of processing, 
with the diversions output in numeric order. It is possible, however, 
to bring back diversions at any time, that is, to append them to the 
current diversion. 


undivert 


brings back all diversions in numeric order, and undivert with 
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arguments brings back the selected diversions in the order given. The 
act of undiverting discards the diverted stuff, as does diverting into a 
diversion whose number is not between 0 and 9 inclusive. 


The value of undivert is not the diverted stuff. Furthermore, the 
diverted material is not rescanned for macros. 


The built-in divnum returns the number of the currently active diver- 
sion. This is zero during normal processing. 


System Command 


You can run any program in the local operating system with the 
syscmd built-in. For example, 


syscmd(date) 


on UNIX runs the date command. Normally sysemd would be used 
to create a file for a subsequent include. 


To facilitate making unique file names, the built-in maketemp is pro- 
vided, with specifications identical to the system function mktemp: a 
string of XXXXX in the argument is replaced by the process id of the 
current process. 


Conditionals 


There is a built-in called ifelse which enables you to perform arbitrary 
conditional testing. In the simplest form, 


ifelse(a, b, c, d) 


compares the two strings a and b. If these are identical, ifelse returns 
the string c; otherwise it returns d. Thus we might define a macro 
called compare which compares two strings and returns “‘yes’’ or 
‘‘no” if they are the same or different. 


define(compare, ‘ifelse($1, $2, yes, no)’) 
Note the quotes, which prevent too-early evaluation of ifelse. 
If the fourth argument is missing, it is treated as empty. 


ifelse can actually have any number of arguments, and thus provides a 
limited form of multi-way decision capability. In the input 
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ifelse(a, b, c, d, e, f, g) 


if the string a matches the string b, the result is c. Otherwise, if d is 
the same as e, the result is f. Otherwise the result is g. If the final 
argument is omitted, the result is null, so 


ifelse(a, b, c) 


is c if a matches b, and null otherwise. 


String Manipulation 


The built-in len returns the length of the string that makes up its 
argument. Thus 


len(abcdef) 
is 6, and len((a,b)) is 5. 


The built-in substr can be used to produce substrings of strings. 
substr(s, i, n) returns the substring of s that starts at the ith position 
(origin zero), and is n characters long. If n is omitted, the rest of the 
string is returned, so 


substr(‘now is the time’, 1) 


ow is the time 
If i or n are out of range, various sensible things happen. 


index(sl, s2) returns the index (position) in s1 where the string s2 
occurs, or —1 if it doesn’t occur. As with substr, the origin for 
strings is 0. 


The built-in translit performs character transliteration. 
translit(s, f, t) 


modifies s by replacing any character found in f by the corresponding 
character of t. That is, 


translit(s, aeiou, 12345) 


replaces the vowels by the corresponding digits. If t is shorter than f, 
characters which don’t have an entry in t are deleted; as a limiting 
case, if t is not present at all, characters from f are deleted from s. 
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So 
translit(s, aeiou) 
deletes vowels from s. 


There is also a built-in called dnl which deletes all characters that fol- 
low it up to and including the next newline; it is useful mainly for 
throwing away empty lines that otherwise tend to clutter up M4 out- 
put. For example, if you say 


define(N, 100) 
define(M, 200) 
define(L, 300) 


the newline at the end of each line is not part of the definition, so it 
is copied into the output, where it may not be wanted. If you add 
dnl to each of these lines, the newlines will disappear. 


Another way to achieve this, due to J. E. Weythman, is 
divert(-1) 
define(...) 


divert 


Printing 
The built-in errprint writes its arguments out on the standard error 
file. Thus you can say 

errprint(‘fatal error’) 
dumpdef is a debugging aid which dumps the current definitions of 
defined terms. If there are no arguments, you get everything; other- 


wise you get the ones you name as arguments. Don’t forget to quote 
the names! 
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Summary of Built-ins 


Each entry is preceded by the page number where it is described. 


S$ changequote(L, R) 

3 define(name, replacement) 
8  divert(number) 

9 divnum 

11 dnl 

11 dumpdef(‘name’, ‘name’, ...) 
11 errprint(s, s, ...) 
eval(numeric expression) 
ifdef(‘name’, this if true, this if false) 
ifelse(a, b, c, d) 

include(file) 

incr(number) 

index(s1, s2) 

len(string) 
maketemp(...XXXXX...) 
sinclude(file) 

substr(string, position, number) 
syscmd(s) 

translit(str, from, to) 
undefine(‘name’) 
undivert(number,number,...) 


raereny 
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BC — An Arbitrary Precision 
Desk-Calculator Language 


Abstract 


BC is a language and a compiler for doing arbitrary precision arith- 
metic on the PDP-11 under the unix time-sharing system. The output 
of the compiler is interpreted and executed by a collection of routines 
which can input, output, and do arithmetic on indefinitely large 
integers and on scaled fixed-point numbers. 


These routines are themselves based on a dynamic storage allocator. 
Overflow does not occur until all available core storage is exhausted. 


The language has a complete control structure as well as immediate- 
mode operation. Functions can be defined and saved for later execu- 
tion. 


Two five hundred-digit numbers can be multiplied to give a thousand 
digit result in about ten seconds. 


A small collection of library functions is also available, including sin, 
cos, arctan, log, exponential, and Bessel functions of integer order. 


Some of the uses of this compiler are 
e to do computation with large integers, 
e to do computation accurate to many decimal places, 


® conversion of numbers from one base to another base. 


Source: Lorinda Cherry, Robert Morris, BC — An Arbitrary Precision Desk- 
Calculator Language (Murray Hill, N.J.: Bell Laboratories, 1978). 
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Introduction 


BC is a language and a compiler for doing arbitrary precision arith- 
metic on the UNIX time-sharing system [1]. The compiler was written 
to make conveniently available a collection of routines (called DC [5]) 
which are capable of doing arithmetic on integers of arbitrary size. 
The compiler is by no means intended to provide a complete pro- 
gramming language. It is a minimal language facility. 


There is a scaling provision that permits the use of decimal point 
notation. Provision is made for input and output in bases other than 
decimal. Numbers can be converted from decimal to octal by simply 
setting the output base to equal 8. 


The actual limit on the number of digits that can be handled depends 
on the amount of storage available on the machine. Manipulation of 
numbers with many hundreds of digits is possible even on the smallest 
versions of UNIX. 


The syntax of BC has been deliberately selected to agree substantially 
with the C language [2]. Those who are familiar with C will find few 
surprises in this language. 


Simple Computations with Integers 


The simplest kind of statement is an arithmetic expression on a line 
by itself. For instance, if you type in the line: 


142857 + 285714 
the program responds immediately with the line 
428571 


The operators —, *, /, %, and ~ can also be used; they indicate sub- 
traction, multiplication, division, remaindering, and exponentiation, 
respectively. Division of integers produces an integer result truncated 
toward zero. Division by zero produces an error comment. 


Any term in an expression may be prefixed by a minus sign to indi- 
cate that it is to be negated (the ‘unary’ minus sign). The expres- 
sion 


7+—3 


is interpreted to mean that —3 is to be added to 7. 
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More complex expressions with several operators and with parentheses 
are interpreted just as in Fortran, with ~ having the greatest binding 
power, then * and % and /, and finally + and -. Contents of 
parentheses are evaluated before material outside the parentheses. 
Exponentiations are performed from right to left and the other opera- 
tors from left to right. The two expressions 


a*b*c and a*(b*c) 
are equivalent, as are the two expressions 
a*b*c and (a*b)*c 
BC shares with Fortran and C the undesirable convention that 
a/b*c is equivalent to (a/b)*c 
Internal storage registers to hold numbers have single lower-case letter 


names. The value of an expression can be assigned to a register in 
the usual way. The statement 


x=x+3 


has the effect of increasing by three the value of the contents of the 
register named x. When, as in this case, the outermost operator is an 
=, the assignment is performed but the result is not printed. Only 26 
of these named storage registers are available. 


There is a built-in square root function whose result is truncated to an 
integer (but see scaling below). The lines 


x = sqrt(191) 
x 


produce the printed result 
13 


Bases 


There are special internal quantities, called “‘ibase’’ and ‘‘obase’’. 
The contents of “‘ibase’’, initially set to 10, determines the base used 
for interpreting numbers read in. For example, the lines 


ibase = 8 
11 
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will produce the output line 
9 


and you are all set up to do octal to decimal conversions. Beware, 
however of trying to change the input base back to decimal by typing 


ibase = 10 


Because the number 10 is interpreted as octal, this statement will have 
no effect. For those who deal in hexadecimal notation, the characters 
A-F are permitted in numbers (no matter what base is in effect) and 
are interpreted as digits having values 10-15 respectively. The state- 
ment 


ibase = A 


will change you back to decimal input base no matter what the 
current input base is. Negative and large positive input bases are per- 
mitted but useless. No mechanism has been provided for the input of 
arbitrary numbers in bases less than 1 and greater than 16. 


The contents of ‘‘obase’’, initially set to 10, are used as the base for 
output numbers. The lines 


obase = 16 
1000 


will produce the output line 
3E8 


which is to be interpreted as a 3-digit hexadecimal number. Very 
large output bases are permitted, and they are sometimes useful. For 
example, large numbers can be output in groups of five digits by set- 
ting “‘obase’’ to 100000. Strange (i.e. 1, 0, or negative) output bases 
are handled appropriately. 


Very large numbers are split across lines with 70 characters per line. 
Lines which are continued end with \. Decimal output conversion is 
practically instantaneous, but output of very large numbers (i.e., 
more than 100 digits) with other bases is rather slow. Non-decimal 
output conversion of a one hundred digit number takes about three 
seconds. 


It is best to remember that ‘‘ibase’”’ and ‘“‘obase”’ have no effect what- 
ever on the course of internal computation or on the evaluation of 
expressions, but only affect input and output conversion, respectively. 
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Scaling 


A third special internal quantity called ‘‘scale’’ is used to determine 
the scale of calculated quantities. Numbers may have up to 99 
decimal digits after the decimal point. This fractional part is retained 
in further computations. We refer to the number of digits after the 
decimal point of a number as its scale. 


When two scaled numbers are combined by means of one of the 
arithmetic operations, the result has a scale determined by the follow- 
ing rules. For addition and subtraction, the scale of the result is the 
larger of the scales of the two operands. In this case, there is never 
any truncation of the result. For multiplications, the scale of the 
result is never less than the maximum of the two scales of the 
operands, never more than the sum of the scales of the operands and, 
subject to those two restrictions, the scale of the result is set equal to 
the contents of the internal quantity “‘scale’’. The scale of a quotient 
is the contents of the internal quantity ‘‘scale’’. The scale of a 
remainder is the sum of the scales of the quotient and the divisor. 
The result of an exponentiation is scaled as if the implied multiplica- 
tions were performed. An exponent must be an integer. The scale of 
a square root is set to the maximum of the scale of the argument and 
the contents of ‘“‘scale’’. 


All of the internal operations are actually carried out in terms of 
integers, with digits being discarded when necessary. In every case 
where digits are discarded, truncation and not rounding is performed. 


The contents of ‘“‘scale’? must be no greater than 99 and no less than 
0. It is initially set to 0. In case you need more than 99 fraction 
digits, you may arrange your own scaling. 


The internal quantities ‘‘scale’’, ‘‘ibase’’, and ‘‘obase’’ can be used in 
expressions just like other variables. The line 


scale = scale + 1 

increases the value of “‘scale’’ by one, and the line 
scale 

causes the current value of ‘‘scale’’ to be printed. 


The value of “‘scale’”’ retains its meaning as a number of decimal 
digits to be retained in internal computation even when “‘ibase’’ or 
“‘obase”’ are not equal to 10. The internal computations (which are 
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still conducted in decimal, regardless of the bases) are performed to 
the specified number of decimal digits, never hexadecimal or octal or 
any other kind of digits. 


Functions 


The name of a function is a single lower-case letter. Function names 
are permitted to collide with simple variable names. Twenty-six dif- 
ferent defined functions are permitted in addition to the twenty-six 
variable names. The line 


define a(x){ 


begins the definition of a function with one argument. This line must 
be followed by one or more statements, which make up the body of 
the function, ending with a right brace }. Return of control from a 
function occurs when a return statement is executed or when the end 
of the function is reached. The return statement can take either of 
the two forms 


return 
return(x) 


In the first case, the value of the function is 0, and in the second, the 
value of the expression in parentheses. 


Variables used in the function can be declared as automatic by a 
statement of the form 


auto x,y,Z 


There can be only one ‘‘auto”’ statement in a function and it must be 
the first statement in the definition. These automatic variables are 
allocated space and initialized to zero on entry to the function and 
thrown away on return. The values of any variables with the same 
names outside the function are not disturbed. Functions may be 
called recursively and the automatic variables at each level of call are 
protected. The parameters named in a function definition are treated 
in the same way as the automatic variables of that function with the 
single exception that they are given a value on entry to the function. 
An example of a function definition is 
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define a(x,y){ 
auto z 
zZ= x*y 
return(z) 


} 


The value of this function, when called, will be the product of its two 
arguments. 


A function is called by the appearance of its name followed by a 
string of arguments enclosed in parentheses and separated by com- 
mas. The result is unpredictable if the wrong number of arguments is 
used. 


Functions with no arguments are defined and called using parentheses 
with nothing between them: b(). 


If the function a above has been defined, then the line 
a(7,3.14) 

would cause the result 21.98 to be printed and the line 
x = a(a(3,4),5) 


would cause the value of x to become 60. 


Subscripted Variables 


A single lower-case letter variable name followed by an expression in 
brackets is called a subscripted variable (an array element). The vari- 
able name is called the array name and the expression in brackets is 
called the subscript. Only one-dimensional arrays are permitted. The 
names of arrays are permitted to collide with the names of simple 
variables and function names. Any fractional part of a subscript is 
discarded before use. Subscripts must be greater than or equal to 
zero and less than or equal to 2047. 


Subscripted variables may be freely used in expressions, in function 
calls, and in return statements. 


An array name may be used as an argument to a function, or may be 
declared as automatic in a function definition by the use of empty 
brackets: 
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f(a[]) 
define f(al[ }) 
auto a[ ] 


When an array name is so used, the whole contents of the array are 
copied for the use of the function, and thrown away on exit from the 
function. Array names which refer to whole arrays cannot be used in 
any other contexts. 


Contro! Statements 


The ‘“‘if’’, the ‘“‘while’, and the ‘‘for”’ statements may be used to alter 
the flow within programs or to cause iteration. The range of each of 
them is a statement or a compound statement consisting of a collec- 
tion of statements enclosed in braces. They are written in the follow- 
ing way 


if(relation) statement 
while(relation) statement 
for(expression!; relation; expression2) statement 


or 


if(relation) {statements} 
while(relation) {statements} 
for(expression1; relation; expression2) {statements} 


A relation in one of the control statements is an expression of the 
form 
x>y 


where two expressions are related by one of the six relational opera- 
tors <, >, <=, >=, ==, or !=. The relation == stands for ‘equal to” 
and != stands for ‘‘not equal to”. The meaning of the remaining 
relational operators is clear. 


CAUTION 


BEWARE of using = instead of == in a relational. Unfor- 
tunately, both of them are legal, so you will not get a diagnos- 
tic message, but = really will not do a comparison. 
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The “‘if’’ statement causes execution of its range if and only if the 
relation is true. Then control passes to the next statement in 
sequence. 


The ‘‘while’” statement causes execution of its range repeatedly as 
long as the relation is true. The relation is tested before each execu- 
tion of its range and if the relation is false, control passes to the next 
statement beyond the range of the while. 


The “for” statement begins by executing “‘expressionl’’. Then the 
relation is tested and, if true, the statements in the range of the ‘“‘for”’ 
are executed. Then ‘‘expression2” is executed. The relation is 
tested, and so on. The typical use of the ‘‘for’’ statement is for a 
controlled iteration, as in the statement 


for(i=1; i<=10; i=i+1) i 


which will print the integers from 1 to 10. Here are some examples 
of the use of the control statements. 


define f(n){ 

auto i, x 

x=1 

for(i=1; i<=n; i=i+1) x=x*i 
return(x) 

+ 


The line 
f(a) 


will print a factorial if a is a positive integer. Here is the definition 
of a function which will compute values of the binomial coefficient (m 
and n are assumed to be positive integers). 


define b(n,m){ 

auto x, j 

x=1 

for(j=1; j<=m; j=jt+1) x=x*(n-jt+)/j 
return(x) 


} 


The following function computes values of the exponential function 
by summing the appropriate series without regard for possible trunca- 
tion errors: 
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scale = 20 
define e(x){ 
auto a, b, c, d,n 


a=1 

b=1 

c=1 

d=0 

n=1 

while(1==1){ 
a= a*x 
b = b*n 
c=c+ a/b 
n=n+1 
if(c==d) return(c) 
d=c 

} 


Some Details 


There are some language features that every user should know about 
even if he will not use them. 


Normally statements are typed one to a line. It is also permissible to 
type several statements on a line separated by semicolons. 


If an assignment statement is parenthesized, it then has a value and it 
can be used anywhere that an expression can. For example, the line 


(x=y+17) 


not only makes the indicated assignment, but also prints the resulting 
value. 


Here is an example of a use of the value of an assignment statement 
even when it is not parenthesized. 


x = afi=i+1] 


causes a value to be assigned to x and also increments i before it is 
used as a subscript. 


The following constructs work in BC in exactly the same manner as 
they do in the C language. Consult the appendix or the C manuals 
[2] for their exact workings. 
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x=y=z is the same as x=(y=z) 


X=t+y x= x+y 
x=-y x=x-y 
x=*y x = x*y 

x =/y x = x/y 
x=%y x= x%y 
x=" y x=x7y 
xt++ (x=x+1)-1 
x— (x=x-1)+1 
++x x = x+1 
—x x = x-l 


Even if you don’t intend to use the constructs, if you type one inad- 
vertently, something correct but unexpected may happen. 


CAUTION 
WARNING! In some of these constructions, spaces are signifi- 
cant. There is a real difference between x =- y and x= -y. 


The first replaces x by x-y and the second by —y. 


Three Important Things 


1. To exit a BC program, type “‘quit’’. 


2. There is a comment convention identical to that of C and of 
PL/I. Comments begin with ‘/*’ and end with ‘*/’. 


3. There is a library of math functions which may be obtained by 
typing at command level 


be -I 


This command will load a set of library functions which, at the 
time of writing, consists of sine (named ‘s’), cosine (‘c’), 
arctangent (‘a’), natural logarithm (‘Il’), exponential (‘e’) and 
Bessel functions of integer order (‘j(n,x)’). Doubtless more 
functions will be added in time. The library sets the scale to 
20. You can reset it to something else if you like. The design 
of these mathematical library routines is discussed elsewhere 


[3]. 
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If you type 
be file ... 


BC will read and execute the named file or files before accepting 
commands from the keyboard. In this way, you may load your favor- 
ite programs and function definitions. 
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Appendix 


Notation 


In the following pages syntactic categories are in italics; literals are in 
bold; material in brackets [] is optional. 


Tokens 


Tokens consist of keywords, identifiers, constants, operators, and 
separators. Token separators may be blanks, tabs or comments. 
Newline characters or semicolons separate statements. 


Comments 


Comments are introduced by the characters /* and terminated by */. 


Identifiers 


There are three kinds of identifiers—ordinary identifiers, array iden- 
tifiers and function identifiers. All three types consist of single 
lower-case letters. Array identifiers are followed by square brackets, 
possibly enclosing an expression describing a subscript. Arrays are 
singly dimensioned and may contain up to 2048 elements. Indexing 
begins at zero so an array may be indexed from 0 to 2047. Subscripts 
are truncated to integers. Function identifiers are followed by 
parentheses, possibly enclosing arguments. The three types of identif- 
iers do not conflict; a program can have a variable named x, an array 
named x and a function named x, all of which are separate and dis- 
tinct. 
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Keywords 


The following are reserved keywords: 


ibase if 
obase break 
scale define 
sqrt auto 
length return 
while quit 
for 

Constants 


Constants consist of arbitrarily long numbers with an optional decimal 
point. The hexadecimal digits A-F are also recognized as digits with 
values 10--15, respectively. 


Expressions 


The value of an expression is printed unless the main operator is an 
assignment. Precedence is the same as the order of presentation here, 
with highest appearing first. Left or right associativity, where appli- 
cable, is discussed with each operator. 


Primitive Expressions 


Named Expressions 


Named expressions are places where values are stored. Simply stated, 
named expressions are legal on the left side of an assignment. The 
value of a named expression is the value stored in the place named. 


identifiers 


Simple identifiers are named expressions. They have an initial 
value of zero. 
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array-name [ expression | 


Array elements are named expressions. They have an initial 
value of zero. 


scale, ibase and obase 


The internal registers scale, ibase and obase are all named 
expressions. scale is the number of digits after the decimal 
point to be retained in arithmetic operations. scale has an ini- 
tial value of zero. ibase and obase are the input and output 
number radix respectively. Both ibase and obase have initial 
values of 10. 


Function Calls 


function-name ([expression[, expression ...]]) 


A function call consists of a function name followed by 
parentheses containing a comma-separated list of expressions, 
which are the function arguments. A whole array passed as an 
argument is specified by the array name followed by empty 
square brackets. All function arguments are passed by value. 
As a result, changes made to the formal parameters have no 
effect on the actual arguments. If the function terminates by 
executing a return statement, the value of the function is the 
value of the expression in the parentheses of the return state- 
ment or is zero if no expression is provided or if there is no 
return statement. 


sqrt ( expression ) 


The result is the square root of the expression. The result is 
truncated in the least significant decimal place. The scale of 
the result is the scale of the expression or the value of scale, 
whichever is larger. 


length ( expression ) 


The result is the total number of significant decimal digits in 
the expression. The scale of the result is zero. 


scale ( expression ) 


The result is the scale of the expression. The scale of the 
result is zero. 
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Constants 


Constants are primitive expressions. 


Parentheses 


An expression surrounded by parentheses is a primitive expression. 
The parentheses are used to alter the normal precedence. 


Unary Operators 


The unary operators bind right to left. 
— expression 
The result is the negative of the expression. 
++ named-expression 


The named expression is incremented by one. The result is 
the value of the named expression after incrementing. 


~—— named-expression 


The named expression is decremented by one. The result is 
the value of the named expression after decrementing. 


named-expression ++ 


The named expression is incremented by one. The result is 
the value of the named expression before incrementing. 


named-expression — 


The named expression is decremented by one. The result is 
the value of the named expression before decrementing. 
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Exponentiation Operator 


The exponentiation operator binds right to left. 
expression ~ expression 


The result is the first expression raised to the power of the 
second expression. The second expression must be an integer. 
If a is the scale of the left expression and b is the absolute 
value of the right expression, then the scale of the result is: 


min (aX b, max (scale, a) ) 


Multiplicative Operators 


The operators *, /, % bind left to right. 
expression * expression 


The result is the product of the two expressions. If a and b 
are the scales of the two expressions, then the scale of the 
result is: 


min (a+b, max (scale, a,b)) 


expression { expression 


The result is the quotient of the two expressions. The scale of 
the result is the value of scale. 


expression Yo expression 


The % operator produces the remainder of the division of the 
two expressions. More precisely, a%b is a—a/b*b. The scale 
of the result is the sum of the scale of the divisor and the value 
of scale. 


Additive Operators 


The additive operators bind left to right. 
expression + expression 


The result is the sum of the two expressions. The scale of the 
result is the maximun of the scales of the expressions. 
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expression — expression 


The result is the difference of the two expressions. The scale 
of the result is the maximum of the scales of the expressions. 


Assignment Operators 


The assignment operators bind right to left. 
named-expression = expression 


This expression results in assigning the value of the expression 
on the right to the named expression on the left. 


named-expression =+ expression 
named-expression =— expression 
named-expression =* expression 
named-expression =/ expression 
named-expression =% expression 


named-expression =~ expression 


The result of the above expressions is equivalent to ‘‘named expres- 
sion = named expression OP expression’, where OP is the operator 
after the = sign. 


Relations 


Unlike all other operators, the relational operators are only valid as 
the object of an if, while, or inside a for statement. 


expression < expression 
expression > expression 
expression <= expression 
expression >= expression 
expression == expression 


expression != expression 
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Storage Classes 


There are only two storage classes in BC, global and automatic 
(local). Only identifiers that are to be local to a function need be 
declared with the auto command. The arguments to a function are 
local to the function. All other identifiers are assumed to be global 
and available to all functions. All identifiers, global and local, have 
initial values of zero. Identifiers declared as auto are allocated on 
entry to the function and released on returning from the function. 
They therefore do not retain values between function calls. auto 
arrays are specified by the array name followed by empty square 
brackets. 


Automatic variables in BC do not work in exactly the same way as in 
either C or PL/I. On entry to a function, the old values of the names 
that appear as parameters and as automatic variables are pushed onto 
a stack. Until return is made from the function, reference to these 
names refers only to the new values. 


Statements 


Statements must be separated by semicolon or newline. Except where 
altered by control statements, execution is sequential. 


Expression Statements 


When a statement is an expression, unless the main operator is an 
assignment, the value of the expression is printed, followed by a new- 
line character. 


Compound Statements 


Statements may be grouped together and used when one statement is 
expected by surrounding them with { }. 
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Quoted String Statements 


“any string” 


This statement prints the string inside the quotes. 


If Statements 


if (relation ) statement 


The substatement is executed if the relation is true. 


While Statements 


while ( relation) statement 


The statement is executed while the relation is true. 


before each execution of the statement. 


For Statements 


for (expression; relation; expression) statement 
The for statement is the same as 


first-expression 

while (relation) { 
Statement 
last-expression 


} 


All three expressions must be present. 


Break Statements 


break 


break causes termination of a for or while statement. 
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The test occurs 


Auto Statements 


auto identifier | ,identifier | 


The auto statement causes the values of the identifiers to be pushed 
down. The identifiers can be ordinary identifiers or array identifiers. 
Array identifiers are specified by following the array name by empty 
square brackets. The auto statement must be the first statement in a 
function definition. 


Define Statements 
define( [parameter | , parameter ...]])< 
statements } 


The define statement defines a function. The parameters may be 
ordinary identifiers or array names. Array names must be followed 
by empty square brackets. 


Return Statements 


return 
return( expression ) 


The return statement causes termination of a function, popping of its 
auto variables, and specifies the result of the function. The first form 
is equivalent to return(0). The result of the function is the result of 
the expression in parentheses. 


Quit 


The quit statement stops execution of a BC program and returns con- 
trol to UNIX when it is first encountered. Because it is not treated as 
an executable statement, it cannot be used in a function definition or 
in an if, for, or while statement. 
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3 


DC — An Interactive Desk Calculator 


Abstract 


DC is an interactive desk calculator program implemented on the 
UNIX time-sharing system to do arbitrary-precision integer arithmetic. 
It has provision for manipulating scaled fixed-point numbers and for 
input and output in bases other than decimal. 


The size of numbers that can be manipulated is limited only by avail- 
able core storage. On typical implementations of UNIX , the size of 
numbers that can be handled varies from several hundred digits on 
the smallest systems to several thousand on the largest. 


Introduction 


DC is an arbitrary precision arithmetic package implemented on the 
UNIX time-sharing system in the form of an interactive desk calcula- 
tor. It works like a stacking calculator using reverse Polish notation. 
Ordinarily DC operates on decimal integers, but one may specify an 
input base, output base, and a number of fractional digits to be main- 
tained. 


A language called BC [1] has been developed which accepts programs 
written in the familiar style of higher-level programming languages 
and compiles output which is interpreted by DC. Some of the com- 
mands described below were designed for the compiler interface and 
are not easy for a human user to manipulate. 


Source: Robert Morris and Lorinda Cherry, DC — An Interactive Desk Calculator 
(Murray Hill, N.J.: Belf Laboratories, 1978). 
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Numbers that are typed into DC are put on a push-down stack. DC 
commands work by taking the top number or two off the stack, per- 
forming the desired operation, and pushing the result on the stack. If 
an argument is given, input is taken from that file until its end, then 
from the standard input. 


Synoptic Description 


Here we describe the DC commands that are intended for use by peo- 
ple. The additional commands that are intended to be invoked by 
compiled output are described in the detailed description. 


Any number of commands are permitted on a line. Blanks and new- 
line characters are ignored except within numbers and in places where 
a register name is expected. 


The following constructions are recognized: 


number The value of the number is pushed onto the main stack. 
A number is an unbroken string of the digits 0-9 and the 
capital letters A-F which are treated as digits with values 
10-15 respectively. The number may be preceded by an 
underscore to input a negative number. Numbers may 
contain decimal points. 


+ -— * The top two values on the stack are added (+), sub- 

Go ~ tracted (-), multiplied (*), divided (/), remaindered 
(%), or exponentiated (~). The two entries are popped 
off the stack; the result is pushed on the stack in their 
place. The result of a division is an integer truncated 
toward zero. See the detailed description below for the 
treatment of numbers with decimal points. An exponent 
must not have any digits after the decimal point. 


sx The top of the main stack is popped and stored into a 
register named x, where x may be any character. If the s 
is capitalized, x is treated as a stack and the value is 
pushed onto it. Any character, even blank or new-line, 
is a valid register name. 


Ix The value in register x is pushed onto the stack. The 
register x is not altered. If the | is capitalized, register x 
is treated as a stack and its top value is popped onto the 
main stack. 
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All registers start with empty value which is treated as a 
zero by the command I and is treated as an error by the 


command L. 

d The top value on the stack is duplicated. 

p The top value on the stack is printed. The top value 
remains unchanged. 

f All values on the stack and in registers are printed. 

x treats the top element of the stack as a character string, 


removes it from the stack, and executes it as a string of 
DC commands. 


[ssa] puts the bracketed character string onto the top of the 
stack. 


q exits the program. If executing a string, the recursion 
level is popped by two. If q is capitalized, the top value 
on the stack is popped and the string execution level is 
popped by that value. 


<x >x =x !<x !>x !=x 


The top two elements of the stack are popped and com- 
pared. Register x is executed if they obey the stated 
relation. Exclamation point is negation. 


< 


replaces the top element on the stack by its square root. 
The square root of an integer is truncated to an integer. 
For the treatment of numbers with decimal points, see 
the detailed description below. 


! interprets the rest of the line as a UNIX command. Con- 
trol returns to DC when the UNIX command terminates. 


c All values on the stack are popped; the stack becomes 
empty. 


i The top value on the stack is popped and used as the 
number radix for further input. If i is capitalized, the 
value of the input base is pushed onto the stack. No 
mechanism has been provided for the input of arbitrary 
numbers in bases less than 1 or greater than 16. 


0 The top value on the stack is popped and used as the 
number radix for further output. If 0 is capitalized, the 
value of the output base is pushed onto the stack. 
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k The top of the stack is popped, and that value is used as 
a scale factor that influences the number of decimal 
places that are maintained during multiplication, divi- 
sion, and exponentiation. The scale factor must be 
greater than or equal to zero and less than 100. If k is 
capitalized, the value of the scale factor is pushed onto 


the stack. 
Zz The value of the stack level is pushed onto the stack. 
4 A line of input is taken from the input source (usually 


the console) and executed. 


Detailed Description 


Internal Representation of Numbers 


Numbers are stored internally using a dynamic storage allocator. 
Numbers are kept in the form of a string of digits to the base 100 
stored one digit per byte (centennial digits). The string is stored with 
the low-order digit at the beginning of the string. For example, the 
representation of 157 is 57,1. After any arithmetic operation on a 
number, care is taken that all digits are in the range 0-99 and that 
the number has no leading zeros. The number zero is represented by 
the empty string. 


Negative numbers are represented in the 100’s complement notation, 
which is analogous to two’s complement notation for binary numbers. 
The high order digit of a negative number is always -1 and all other 
digits are in the range 0-99. The digit preceding the high order ~1 
digit is never a 99. The representation of -157 is 43,98,-1. We shall 
call this the canonical form of a number. The advantage of this kind 
of representation of negative numbers is ease of addition. When 
addition is performed digit by digit, the result is formally correct. 
The result need only be modified, if necessary, to put it into canoni- 
cal form. 


Because the largest valid digit is 99 and the byte can hold numbers 
twice that large, addition can be carried out and the handling of car- 
ries done later when that is convenient, as it sometimes is. 


An additional byte is stored with each number beyond the high order 
digit to indicate the number of assumed decimal digits after the 
decimal point. The representation of .001 is 1,3 where the scale has 


3—4 Programmer's Guide: CTIX Supplement 


been italicized to emphasize the fact that it is not the high order digit. 
The value of this extra byte is called the scale factor of the number. 


The Allocator 


DC uses a dynamic string storage allocator for all of its internal 
storage. All reading and writing of numbers internally is done 
through the allocator. Associated with each string in the allocator is 
a four-word header containing pointers to the beginning of the string, 
the end of the string, the next place to write, and the next place to 
read. Communication between the allocator and DC is done via 
pointers to these headers. 


The allocator initially has one large string on a list of free strings. All 
headers except the one pointing to this string are on a list of free 
headers. Requests for strings are made by size. The size of the 
string actually supplied is the next higher power of 2. When a 
request for a string is made, the allocator first checks the free list to 
see if there is a string of the desired size. If none is found, the allo- 
cator finds the next larger free string and splits it repeatedly until it 
has a string of the right size. Left-over strings are put on the free 
list. If there are no larger strings, the allocator tries to coalesce 
smaller free strings into larger ones. Since all strings are the result of 
splitting large strings, each string has a neighbor that is next to it in 
core and, if free, can be combined with it to make a string twice as 
long. This is an implementation of the ‘“‘buddy system’’ of allocation 
described in [2]. 


Failing to find a string of the proper length after coalescing, the allo- 
cator asks the system for more space. The amount of space on the 
system is the only limitation on the size and number of strings in DC. 
If at any time in the process of trying to allocate a string, the alloca- 
tor runs out of headers, it also asks the system for more space. 


There are routines in the allocator for reading, writing, copying, 
rewinding, forward-spacing, and backspacing strings. All string 
manipulation is done using these routines. 


The reading and writing routines increment the read pointer or write 
pointer so that the characters of a string are read or written in succes- 
sion by a series of read or write calls. The write pointer is interpreted 
as the end of the information-containing portion of a string and a call 
to read beyond that point returns an end-of-string indication. An 
attempt to write beyond the end of a string causes the allocator to 
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allocate a larger space and then copy the old string into the larger 
block. 


Internal Arithmetic 


All arithmetic operations are done on integers. The operands (or 
operand) needed for the operation are popped from the main stack 
and their scale factors stripped off. Zeros are added or digits 
removed as necessary to get a properly scaled result from the internal 
arithmetic routine. For example, if the scale of the operands is dif- 
ferent and decimal alignment is required, as it is for addition, zeros 
are appended to the operand with the smaller scale. After perform- 
ing the required arithmetic operation, the proper scale factor is 
appended to the end of the number before it is pushed on the stack. 


A register called scale plays a part in the results of most arithmetic 
operations. scale is the bound on the number of decimal places 
retained in arithmetic computations. scale may be set to the number 
on the top of the stack truncated to an integer with the k command. 
K may be used to push the value of scale on the stack. scale must be 
greater than or equal to 0 and less than 100. The descriptions of the 
individual arithmetic operations will include the exact effect of scale 
on the computations. 


Addition and Subtraction 


The scales of the two numbers are compared and trailing zeros are 
supplied to the number with the lower scale to give both numbers the 
same scale. The number with the smaller scale is multiplied by 10 if 
the difference of the scales is odd. The scale of the result is then set 
to the larger of the scales of the two operands. 


Subtraction is performed by negating the number to be subtracted and 
proceeding as in addition. 


Finally, the addition is performed digit by digit from the low order 
end of the number. The carries are propagated in the usual way. 
The resulting number is brought into canonical form, which may 
require stripping of leading zeros, or for negative numbers replacing 
the high-order configuration 99,—1 by the digit -1. In any case, digits 
which are not in the range 0-99 must be brought into that range, pro- 
pagating any carries or borrows that result. 
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Multiplication 


The scales are removed from the two operands and saved. The 
operands are both made positive. Then multiplication is performed 
in a digit by digit manner that exactly mimics the hand method of 
multiplying. The first number is multiplied by each digit of the 
second number, beginning with its low order digit. The intermediate 
products are accumulated into a partial sum which becomes the final 
product. The product is put into the canonical form and its sign is 
computed from the signs of the original operands. 


The scale of the result is set equal to the sum of the scales of the two 
operands. If that scale is larger than the internal register scale and 
also larger than both of the scales of the two operands, then the scale 
of the result is set equal to the largest of these three last quantities. 


Division 


The scales are removed from the two operands. Zeros are appended 
or digits removed from the dividend to make the scale of the result of 
the integer division equal to the internal quantity scale. The signs are 
removed and saved. 


Division is performed much as it would be done by hand. The differ- 
ence of the lengths of the two numbers is computed. If the divisor is 
longer than the dividend, zero is returned. Otherwise the top digit of 
the divisor is divided into the top two digits of the dividend. The 
result is used as the first (high-order) digit of the quotient. It may 
turn out be one unit too low, but if it is, the next trial quotient will 
be larger than 99 and this will be adjusted at the end of the process. 
The trial digit is multiplied by the divisor and the result subtracted 
from the dividend and the process is repeated to get additional quo- 
tient digits until the remaining dividend is smaller than the divisor. 
At the end, the digits of the quotient are put into the canonical form, 
with propagation of carry as needed. The sign is set from the sign of 
the operands. 
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Remainder 


The division routine is called and division is performed exactly as 
described. The quantity returned is the remains of the dividend at 
the end of the divide process. Since division truncates toward zero, 
remainders have the same sign as the dividend. The scale of the 
remainder is set to the maximum of the scale of the dividend and the 
scale of the quotient plus the scale of the divisor. 


Square Root 


The scale is stripped from the operand. Zeros are added if necessary 
to make the integer result have a scale that is the larger of the inter- 
nal quantity scale and the scale of the operand. 


The method used to compute sqrt(y) is Newton’s method with succes- 
sive approximations by the rule 


Ant+1 = (x, + 7) 
n 


The initial guess is found by taking the integer square root of the top 
two digits. 


Exponentiation 


Only exponents with zero scale factor are handled. If the exponent is 
zero, then the result is 1. If the exponent is negative, then it is made 
positive and the base is divided into one. The scale of the base is 
removed. 


The integer exponent is viewed as a binary number. The base is 
repeatedly squared and the result is obtained as a product of those 
powers of the base that correspond to the positions of the one-bits in 
the binary representation of the exponent. Enough digits of the result 
are removed to make the scale of the result the same as if the indi- 
cated multiplication had been performed. 
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Input Conversion and Base 


Numbers are converted to the internal representation as they are read 
in. The scale stored with a number is simply the number of fractional 
digits input. Negative numbers are indicated by preceding the 
number with a _ (an underscore). The hexadecimal digits A-F 
correspond to the numbers 10-15 regardless of input base. The i 
command can be used to change the base of the input numbers. This 
command pops the stack, truncates the resulting number to an 
integer, and uses it as the input base for all further input. The input 
base is initialized to 10 but may, for example be changed to 8 or 16 to 
do octal or hexadecimal to decimal conversions. The command I will 
push the value of the input base on the stack. 


Output Commands 


The command p causes the top of the stack to be printed. It does not 
remove the top of the stack. All of the stack and internal registers 
can be output by typing the command f. The o command can be 
used to change the output base. This command uses the top of the 
stack, truncated to an integer as the base for all further output. The 
output base in initialized to 10. It will work correctly for any base. 
The command O pushes the value of the output base on the stack. 


Output Format and Base 


The input and output bases only affect the interpretation of numbers 
on input and output; they have no effect on arithmetic computations. 
Large numbers are output with 70 characters per line; a \ indicates a 
continued line. All choices of input and output bases work correctly, 
although not all are useful. A particularly useful output base is 
100000, which has the effect of grouping digits in fives. Bases of 8 
and 16 can be used for decimal-octal or decimal-hexadecimal conver- 
sions. 
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Internal Registers 


Numbers or strings may be stored in internal registers or loaded on 
the stack from registers with the commands s and 1. The command sx 
pops the top of the stack and stores the result in register x. x can be 
any character. Lx puts the contents of register x on the top of the 
stack. The 1 command has no effect on the contents of register x. 
The s command, however, is destructive. 


Stack Commands 


The command c clears the stack. The command d pushes a duplicate 
of the number on the top of the stack on the stack. The command z 
pushes the stack size on the stack. The command X replaces the 
number on the top of the stack with its scale factor. The command Z 
replaces the top of the stack with its length. 


Subroutine Definitions and Calls 


Enclosing a string in { ] pushes the ascii string on the stack. The q 
command quits or in executing a string, pops the recursion levels by 
two. 


Internal Registers — Programming DC 


The load and store commands together with [ ] to store strings, x to 
execute and the testing commands ‘<’, ‘>’, ‘=’, ‘!<’, ‘!>’, ‘!=" can be 
used to program DC. The x command assumes the top of the stack is 
an string of DC commands and executes it. The testing commands 
compare the top two elements on the stack and if the relation holds, 
execute the register that follows the relation. For example, to print 
the numbers 0-9, 


{lipl+ si li10>a]sa 
Qsi_ lax 
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Push-down Registers and Arrays 


These commands were designed for used by a compiler, not by peo- 
ple. They involve push-down registers and arrays. In addition to the 
stack that commands work on, DC can be thought of as having indivi- 
dual stacks for each register. These registers are operated on by the 
commands § and L. Sx pushes the top value of the main stack onto 
the stack for the register x. Lx pops the stack for register x and puts 
the result on the main stack. The commands s and I also work on 
registers but not as push-down stacks. 1 doesn’t effect the top of the 
register stack, and s destroys what was there before. 


The commands to work on arrays are : and ;. :x pops the stack and 
uses this value as an index into the array x. The next element on the 
stack is stored at this index in x. An index must be greater than or 
equal to 0 and less than 2048. 3x is the command to load the main 
stack from the array x. The value on the top of the stack is the index 
into the array x of the value to be loaded. 


Miscellaneous Commands 


The command ! interprets the rest of the line as a UNIX command 
and passes it to UNIX to execute. One other compiler command is Q. 
This command uses the top of the stack as the number of levels of 
recursion to skip. 


Design Choices 


The real reason for the use of a dynamic storage allocator was that a 
general purpose program could be (and in fact has been) used for a 
variety of other tasks. The allocator has some value for input and for 
compiling (i.e. the bracket [...] commands) where it cannot be 
known in advance how long a string will be. The result was that at a 
modest cost in execution time, all considerations of string allocation 
and sizes of strings were removed from the remainder of the program 
and debugging was made easier. The allocation method used wastes 
approximately 25% of available space. 


The choice of 100 as a base for internal arithmetic seemingly has no 
compelling advantage. Yet the base cannot exceed 127 because of 


DC — An Interactive Desk Calculator 3—I1 


hardware limitations and at the cost of 5% in space, debugging was 
made a great deal easier and decimal output was made much faster. 


The reason for a stack-type arithmetic design was to permit all DC 
commands from addition to subroutine execution to be implemented 
in essentially the same way. The result was a considerable degree of 
logical separation of the final program into modules with very little 
communication between modules. 


The rationale for the lack of interaction between the scale and the 
bases was to provide an understandable means of proceeding after a 
change of base or scale when numbers had already been entered. An 
earlier implementation which had global notions of scale and base did 
not work out well. If the value of scale were to be interpreted in the 
current input or output base, then a change of base or scale in the 
midst of a computation would cause great confusion in the interpreta- 
tion of the results. The current scheme has the advantage that the 
value of the input and output bases are only used for input and out- 
put, respectively, and they are ignored in all other operations. The 
value of scale is not used for any essential purpose by any part of the 
program and it is used only to prevent the number of decimal places 
resulting from the arithmetic operations from growing beyond all 
bounds. 


The design rationale for the choices for the scales of the results of 
arithmetic were that in no case should any significant digits be thrown 
away if, on appearances, the user actually wanted them. Thus, if the 
user wants to add the numbers 1.5 and 3.517, it seemed reasonable to 
give him the result 5.017 without requiring him to unnecessarily 
specify his rather obvious requirements for precision. 


On the other hand, multiplication and exponentiation produce results 
with many more digits than their operands and it seemed reasonable 
to give as a minimum the number of decimal places in the operands 
but not to give more than that number of digits unless the user asked 
for them by specifying a value for scale. Square root can be handled 
in just the same way as multiplication. The operation of division 
gives arbitrarily many decimal places and there is simply no way to 
guess how many places the user wants. In this case only, the user 
must specify a scale to get any decimal places at all. 


The scale of remainder was chosen to make it possible to recreate the 
dividend from the quotient and remainder. This is easy to imple- 
ment; no digits are thrown away. 
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An Introduction to Display Editing with VI 


Introduction 


Vi (visual) is a display oriented interactive text editor. When using vi 
the screen of your terminal acts as a window into the file which you 
are editing. Changes which you make to the file are reflected in what 
you see. 


Using vi you can insert new text any place in the file quite easily. 
Most of the commands to vi move the cursor around in the file. 
There are commands to move the cursor forward and backward in 
units of characters, words, sentences and paragraphs. A small set of 
operators, like d for delete and ¢ for change, are combined with the 
motion commands to form operations such as delete word or change 
paragraph, in a simple and natural way. This regularity and the 
mnemonic assignment of commands to keys makes the editor com- 
mand set easy to remember and to use. 


Vi will work on a large number of display terminals, and new termi- 
nals are easily driven after editing a terminal description file. While 
it is advantageous to have an intelligent terminal which can locally 
insert and delete lines and characters from the display, the editor will 
function quite well on dumb terminals over slow phone lines. The 
editor makes allowance for the low bandwidth in these situations and 
uses smaller window sizes and different display updating algorithms to 
make best use of the limited speed available. 


It is also possible to use the command set of wi on hardcopy terminals, 


storage tubes and “‘glass tty’s’’ using a one line editing window; thus 
vi’s command set is available on all terminals. The full command set 


Source: William Joy and Mark Horton, An Introduction to Display Editing with VI 
(Berkeley, CA: University of California). 
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of the more traditional, line oriented editor ex is available within wi; 
it is quite simple to switch between the two modes of editing. 


1. Getting Started 


This document provides a quick introduction to wi. (Pronounced 
vee-eye.) You should be running vi on a file you are familiar with 
while you are reading this. The first part of this document (sections 1 
through 5) describes the basics of using vi. Some topics of special 
interest are presented in section 6, and some nitty-gritty details of 
how the editor functions are saved for section 7 to avoid cluttering 
the presentation here. 


There is also a short appendix here, which gives for each character 
the special meanings which this character has in vi. Attached to this 
document should be a quick reference card. This card summarizes 
the commands of vi in a very compact format. You should have the 
card handy while you are learning wi. 


1.1 Specifying Terminal Type 


Before you can start vi you must tell the system what kind of terminal 
you are using. Here is a (necessarily incomplete) list of terminal type 
codes. If your terminal docs not appear here, you should consult 
with one of the staff members on your system to find out the code for 
your terminal. If your terminal does not have a code, one can be 
assigned and a description for the terminal can be created. 


Code Full Name Type 
2621 Hewlett-Packard 2621 A/P Intelligent 
2645 Hewlett-Packard 264x Intelligent 
act4 Microterm ACT-IV Dumb 
actS Microterm ACT-V Dumb 
adm3a Lear Siegler ADM-3a Dumb 
adm31 Lear Siegler ADM-31 Intelligent 
c100 Human Design Concept 100 Intelligent 
dm1520 Datamedia 1520 Dumb 
dm2500  Datamedia 2500 Intelligent 
dm3025  Datamedia 3025 Intelligent 
fox Perkin-Elmer Fox Dumb 
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h1500 Hazeltine 1500 Intelligent 


h19 Heathkit h19 Intelligent 
i100 Infoton 100 Intelligent 
mime Imitating a smart act4 Intelligent 
t1061 Teleray 1061 Intelligent 
vt52 Dec VT-52 Dumb 


Suppose for example that you have a Hewlett-Packard HP2621A ter- 
minal. The code used by the system for this terminal is ‘2621’. In 
this case you can use one of the following commands to tell the sys- 
tem the type of your terminal: 


% setenv TERM 2621 


This command works with the csh shell. If you are using the stan- 
dard Bourne shell sh then you should give the commands 


$ TERM=2621 
$ export TERM 


If you want to arrange to have your terminal type set up automati- 
cally when you log in, you can use the tser program. If you dial in on 
a mime, but often use hardwired ports, a typical line for your ./ogin 
file (if you use csh) would be 


setenv TERM ~ tset — —-d mime~ 
or for your .profile file (if you use sh) 
TERM=-~ tset - —d mime 


Tset knows which terminals are hardwired to each port and needs 
only to be told that when you dial in you are probably on a mime. 
Tset is usually used to change the erase and kill characters, too. 


1.2 Editing a File 


After telling the system which kind of terminal you have, you should 
make a copy of a file you are familiar with, and run vi on this file, 
giving the command 


% vi name 


replacing name with the name of the copy file you just created. The 
screen should clear and the text of your file should appear on the 
screen. If something else happens refer to the footnote.! 
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1.3 The Editor’s Copy: The Buffer 


The editor does not directly modify the file which you are editing. 
Rather, the editor makes a copy of this file, in a place called the 
buffer, and remembers the file’s name. You do not affect the con- 
tents of the file unless and until you write the changes you make back 
into the original file. 


1.4 Notational Conventions 


In our examples, input which must be typed as is will be presented in 
bold face. Text which should be replaced with appropriate input will 
be given in italics. We will represent special characters in SMALL 
CAPITALS. 


1.5 Arrow Keys 


The editor command set is independent of the terminal you are using. 
On most terminals with cursor positioning keys, these keys will also 
work within the editor. If you don't have cursor positioning keys, or 
even if you do, you can use the h j k and I keys as cursor positioning 
keys (these are labelled with arrows on an adm3a).” 


1. If you gave the system an incorrect terminal type code then the editor may 
have just made a mess out of your screen. This happens when it sends control 
codes for one kind of terminal to some other kind of terminal. In this case hit 
the keys :q (colon and the q key) and then hit the RETURN key. This should 
get you back to the command level interpreter. Figure out what you did wrong 
(ask someone else if necessary) and try again. 


Another thing which can go wrong is that you typed the wrong file name and 
the editor just printed an error diagnostic. In this case you should follow the 
above procedure for getting out of the editor, and try again this time spelling 
the file name correctly. 


If the editor doesn’t seem to respond to the commands which you type here, try 
sending an interrupt to it by hitting the DEL or RUB key on your terminal, and 
then hitting the :q command again followed by a carriage return. 

2. As we will see later, h moves back to the left (like control-h which is a 
backspace), j moves down (in the same column), k moves up (in the same 
column), and / moves to the right. 


4—4 Programmer's Guide: CTIX Supplement 


(Particular note for the HP2621: on this terminal the function keys 
must be shifted (ick) to send to the machine, otherwise they only act 
locally. Unshifted use will leave the cursor positioned incorrectly.) 


1.6 Special Characters: ESC, CR and DEL 


Several of these special characters are very important, so be sure to 
find them right now. Look on your keyboard for a key labelled Esc 
or ALT. It should be near the upper left corner of your terminal. 
Try hitting this key a few times. The editor will ring the bell to indi- 
cate that it is in a quiescent state.* Partially formed commands are 
cancelled by ESC, and when you insert text in the file you end the text 
insertion with ESC. This key is a fairly harmless one to hit, so you 
can just hit it if you don’t know what is going on until the editor rings 
the bell. 


The CR or RETURN key is important because it is used to terminate 
certain commands. It is usually at the right side of the keyboard, and 
is the same command used at the end of each shell command. 


Another very useful key is the DEL or RUB key, which generates an 
interrupt, telling the editor to stop what it is doing. It is a forceful 
way of making the editor listen to you, or to return it to the quiescent 
state if you don’t know or don’t like what is going on. Try hitting 
the ‘/ key on your terminal. This key is used when you want to 
specify a string to be searched for. The cursor should now be posi- 
tioned at the bottom line of the terminal after a ‘/ printed as a 
prompt. You can get the cursor back to the current position by hit- 
ting the DEL or RUB key; try this now.* From now on we will simply 
refer to hitting the DEL or RUB key as “‘sending an interrupt.’” 


The editor often echoes your commands on the last line of the termi- 
nal. If the cursor is on the first position of this last line, then the edi- 
tor is performing a computation, such as computing a new position in 
the file after a search or running a command to reformat part of the 


3. On smart terminals where it is possible, the editor will quietly flash the screen 
rather than ringing the bell. 

Backspacing over the ‘/’ will also cancel the search. 

On some systems, this interruptibility comes at a price: you cannot type ahead 
when the editor is computing with the cursor on the bottom line. 


ih 
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buffer. When this is happening you can stop the editor by sending an 
interrupt. 


1.7 Getting Out of the Editor 


After you have worked with this introduction for a while, and you 
wish to do something else, you can give the command ZZ to the edi- 
tor. This will write the contents of the editor’s buffer back into the 
file you are editing, if you made any changes, and then quit from the 
editor. You can also end an editor session by giving the command 
:q!CR:® this is a dangerous but occasionally essential command which 
ends the editor session and discards all your changes. You need to 
know about this command in case you change the editor’s copy of a 
file you wish only to look at. Be very careful not to give this com- 
mand when you really want to save the changes you have made. 


2. Moving Around in the File 


2.1 Scrolling and Paging 


The editor has a number of commands for moving around in the file. 
The most useful of these is generated by hitting the control and D 
keys at the same time, a control-D or ‘~D’. We will use this two 
character notation for referring to these control keys from now on. 
You may have a key labelled *~’ on your terminal. This key will be 
represented as ‘t in this document; ‘~” is exclusively used as part of 
the ‘>x’ notation for control characters.’ 


As you know now if you tried hitting ~D, this command scrolls down 
in the file. The D thus stands for down. Many editor commands are 
mnemonic and this makes them much easier to remember. For 
instance the command to scroll up is ~U. Many dumb terminals can’t 


6. All commands which read from the last display line can also be terminated with 
a ESC as well as an CR. 

7. If you don’t have a ‘~’ key on your terminal then there is probably a key 
labelled ‘t’; in any case these characters are one and the same. 
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scroll up at all, in which case hitting ~U clears the screen and 
refreshes it with a line which is farther back in the file at the top. 


If you want to see more of the file below where you are, you can hit 
“E to expose one more line at the bottom of the screen, leaving the 
cursor where it is. The command ~Y (which is hopelessly non- 
mnemonic, but next to ~U on the keyboard) exposes one more line at 
the top of the screen. 


There are other ways to move around in the file; the keys ~F and ~B 
move forward and backward a page, keeping a couple of lines of con- 
tinuity between screens so that it is possible to read through a file 
using these rather than ~D and ~U if you wish. 


Notice the difference between scrolling and paging. If you are trying 
to read the text in a file, hitting ~F to move forward a page will leave 
you only a little context to look back at. Scrolling on the other hand 
leaves more context, and happens more smoothly. You can continue 
to read the text as scrolling is taking place. 


2.2 Searching, Goto, and Previous Context 


Another way to position yourself in the file is by giving the editor a 
string to search for. Type the character / followed by a string of char- 
acters terminated by CR. The editor will position the cursor at the 
next occurrence of this string. Try hitting n to then go to the next 
occurrence of this string. The character ? will search backwards from 
where you are, and is otherwise like /.® 


If the search string you give the editor is not present in the file the 
editor will print a diagnostic on the last line of the screen, and the 
cursor will be returned to its initial position. 


If you wish the search to match only at the beginning of a line, begin 
the search string with an t. To match only at the end of a line, end 
the search string with a $. Thus /tsearchCR will search for the word 


8. These searches will normally wrap around the end of the file, and thus find the 
string even if it is not on a line in the direction you search provided it is 
anywhere else in the file. You can disable this wraparound in scans by giving 
the command ‘se nowrapscanCR, or more briefly :se nowsCR. 
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“search”? at the beginning of a line, and /last$CR searches for the 
word “‘last’’ at the end of a line.” 


The command G, when preceded by a number will position the cursor 
at that line in the file. Thus 1G will move the cursor to the first line 
of the file. If you give G no count, then it moves to the end of the 
file. 


If you are near the end of the file, and the last line is not at the bot- 
tom of the screen, the editor will place only the character ‘~’ on each 
remaining line. This indicates that the last line in the file is on the 
screen; that is, the ‘~’ lines are past the end of the file. 


You can find out the state of the file you are editing by typing a ~G. 
The editor will show you the name of the file you are editing, the 
number of the current line, the number of lines in the buffer, and the 
percentage of the way through the buffer which you are. Try doing 
this now, and remember the number of the line you are on. Give a 
G command to get to the end and then another G command to get 
back where you were. 


You can also get back to a previous position by using the command 
>> (two back quotes). This is often more convenient than G because 
it requires no advance preparation. Try giving a G or a search with / 
or ? and then a ~~ to get back to where you were. If you acciden- 
tally hit n or any command which moves you far away from a context 
of interest, you can quickly get back by hitting ~~. 


2.3 Moving Around on the Screen 


Now try just moving the cursor around on the screen. If your termi- 
nal has arrow keys (4 or 5 keys with arrows going in each direction) 
try them and convince yourself that they work. If you don’t have 
working arrow keys, you can always use h, j, k, and1. Experienced 
users of vi prefer these keys to arrow keys, because they are usually 
right underneath their fingers. 


9. Actually, the string you give to search for here can be a regular expression in 
the sense of the editors ex (1) and ed (1). If you don’t wish to learn about this 
yet, you can disable this more general facility by doing :se nomagicCR; by 
putting this command in EXINIT in your environment, you can have this 
always be in effect (more about EX/NIT later.) 
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Hit the + key. Each time you do, notice that the cursor advances to 
the next line in the file, at the first non-white position on the line. 
The — key is like + but goes the other way. 


These are very common keys for moving up and down lines in the 
file. Notice that if you go off the bottom or top with these keys then 
the screen will scroll down (and up if possible) to bring a line at a 
time into view. The RETURN key has the same effect as the + key. 


Vi also has commands to take you to the top, middle and bottom of 
the screen. H will take you to the top (home) line on the screen. 
Try preceding it with a number as in 3H. This will take you to the 
third line on the screen. Many vi commands take preceding numbers 
and do interesting things with them. Try M, which takes you to the 
middle line on the screen, and L, which takes you to the last line on 
the screen. L also takes counts, thus 5L will take you to the fifth line 
from the bottom. 


2.4 Moving within a Line 


Now try picking a word on some line on the screen, not the first word 
on the line. Move the cursor using RETURN and — to be on the line 
where the word is. Try hitting the w key. This will advance the cur- 
sor to the next word on the line. Try hitting the b key to back up 
words in the line. Also try the e key which advances you to the end 
of the current word rather than to the beginning of the next word. 
Also try SPACE (the space bar) which moves right one character and 
the BS (backspace or ~H) key which moves left one character. The 
key h works as ~H does and is useful if you don’t have a BS key. 
(Also, as noted just above, | will move to the right.) 


If the line had punctuation in it you may have noticed that that the w 
and b keys stopped at each group of punctuation. You can also go 
back and forwards words without stopping at punctuation by using W 
and B rather than the lower case equivalents. Think of these as 
bigger words. Try these on a few lines with punctuation to see how 
they differ from the lower case w and b. 


The word keys wrap around the end of line, rather than stopping at 
the end. Try moving to a word on a line below where you are by 
repeatedly hitting w. 
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2.5 Summary 


SPACE 
“B 
“D 
°E 
“F 
“G 


~eservsgremawy~'! + 


2.6 View 


advance the cursor one position 
backwards to previous page 

scrolls down in the file 

exposes another line at the bottom 
forward to next page 

tell what is going on 

backspace the cursor 

next line, same column 

previous line, same column 

scrolls up in the file 

exposes another line at the top 
next line, at the beginning 
previous line, at the beginning 
scan for a following string forwards 
scan backwards 

back a word, ignoring punctuation 
go to specified line, last default 
home screen line 

middle screen line 

last screen line 

forward a word, ignoring punctuation 
back a word 

end of current word 

scan for next instance of / or ? pattern 
word after this word 


If you want to use the editor to look at a file, rather than to make 
changes, invoke it as view instead of vi. This will set the readonly 
option which will prevent you from accidently overwriting the file. 


4—10 Programmer's Guide: CTIX Supplement 


3. Making Simple Changes 
3.1 Inserting 


One of the most useful commands is the i (insert) command. After 
you type i, everything you type until you hit ESC is inserted into the 
file. Try this now; position yourself to some word in the file and try 
inserting text before this word. If you are on an dumb terminal it 
will seem, for a minute, that some of the characters in your line have 
been overwritten, but they will reappear when you hit ESC. 


Now try finding a word which can, but does not, end in an ‘s’. Posi- 
tion yourself at this word and type e (move to end of word), then a 
for append and then ‘sESC’ to terminate the textual insert. This 
sequence of commands can be used to easily pluralize a word. 


Try inserting and appending a few times to make sure you understand 
how this works; i placing text to the left of the cursor, a to the right. 


It is often the case that you want to add new lines to the file you are 
editing, before or after some specific line in the file. Find a line 
where this makes sense and then give the command 0 to create a new 
line after the line you are on, or the command O to create a new line 
before the line you are on. After you create a new line in this way, 
text you type up to an ESC is inserted on the new line. 


Many related editor commands are invoked by the same letter key 
and differ only in that one is given by a lower case key and the other 
is given by an upper case key. In these cases, the upper case key 
often differs from the lower case key in its sense of direction, with the 
upper case key working backward and/or up, while the lower case key 
moves forward and/or down. 


Whenever you are typing in text, you can give many lines of input or 
just a few characters. To type in more than one line of text, hit a 
RETURN at the middle of your input. A new line will be created for 
text, and you can continue to type. If you are on a slow and dumb 
terminal the editor may choose to wait to redraw the tail of the 
screen, and will let you type over the existing screen lines. This 
avoids the lengthy delay which would occur if the editor attempted to 
keep the tail of the screen always up to date. The tail of the screen 
will be fixed up, and the missing lines will reappear, when you hit 
ESC. 


While you are inserting new text, you can use the characters you nor- 
mally use at the system command level (usually ~H or #) to 
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backspace over the last character which you typed, and the character 
which you use to kill input lines (usually @, ~X, or ~U) to erase the 
input you have typed on the current line.!° The character ~W will 
erase a whole word and leave you after the space after the previous 
word; it is useful for quickly backing up in an insert. 


Notice that when you backspace during an insertion the characters 
you backspace over are not erased; the cursor moves backwards, and 
the characters remain on the display. This is often useful if you are 
planning to type in something similar. In any case the characters 
disappear when when you hit ESC; if you want to get rid of them 
immediately, hit an ESC and then a again. 


Notice also that you can’t erase characters which you didn’t insert, 
and that you can’t backspace around the end of a line. If you need to 
back up to the previous line to make a correction, just hit ESC and 
move the cursor back to the previous line. After making the correc- 
tion you can return to where you were and use the insert or append 
command again. 


3.2 Making Small Corrections 


You can make small corrections in existing text quite easily. Find a 
single character which is wrong or just pick any character. Use the 
arrow keys to find the character, or get near the character with the 
word motion keys and then either backspace (hit the BS key or ~H or 
even just h) or SPACE (using the space bar) until the cursor is on the 
character which is wrong. If the character is not needed then hit the 
x key; this deletes the character from the file. It is analogous to the 
way you x out characters when you make mistakes on a typewriter 
(except it’s not as messy). 


If the character is incorrect, you can replace it with the correct char- 
acter by giving the command rc, where c is replaced by the correct 
character. Finally if the character which is incorrect should be 
replaced by more than one character, give the command s which sub- 
stitutes a string of characters, ending with ESC, for it. If there are a 
small number of characters which are wrong you can precede s with a 


10. In fact, the character ~H (backspace) always works to erase the last input 
character here, regardless of what your erase character is. 
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count of the number of characters to be replaced. Counts are also 
useful with x to specify the number of characters to be deleted. 


3.3 More Corrections: Operators 


You already know almost enough to make changes at a higher level. 
All you need to know now is that the d key acts as a delete operator. 
Try the command dw to delete a word. Try hitting . a few times. 
Notice that this repeats the effect of the dw. The command . repeats 
the last command which made a change. You can remember it by 
analogy with an ellipsis ‘.... 


Now try db. This deletes a word backwards, namely the preceding 
word. Try dSPACE. This deletes a single character, and is equivalent 
to the x command. 


Another very useful operator is c or change. The command ew thus 
changes the text of a single word. You follow it by the replacement 
text ending with an Esc. Find a word which you can change to 
another, and try this now. Notice that the end of the text to be 
changed was marked with the character ‘$’ so that you can see this as 
you are typing in the new material. 


3.4 Operating on Lines 


It is often the case that you want to operate on lines. Find a line 
which you want to delete, and type dd, the d operator twice. This 
will delete the line. If you are on a dumb terminal, the editor may 
just erase the line on the screen, replacing it with a line with only an 
@ on it. This line does not correspond to any line in your file, but 
only acts as a place holder. It helps to avoid a lengthy redraw of the 
rest of the screen which would be necessary to close up the hole 
created by the deletion on a terminal without a delete line capability. 


Try repeating the c operator twice; this will change a whole line, eras- 
ing its previous contents and replacing them with text you type up to 
an Esc.!! 


11. The command S is a convenient synonym for for ec, by analogy with s. Think 
of S as a substitute on lines, while s is a substitute on characters. 
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You can delete or change more than one line by preceding the dd or 
ce with a count, i.e. 5dd deletes 5 lines. You can also give a com- 
mand like dL to delete all the lines up to and including the last line 
on the screen, or d3L to delete through the third from the bottom 
line. Try some commands like this now.'? Notice that the editor lets 
you know when you change a large number of lines so that you can 
see the extent of the change. The editor will also always tell you 
when a change you make affects text which you cannot see. 


3.5 Undoing 


Now suppose that the last change which you made was incorrect; you 
could use the insert, delete and append commands to put the correct 
material back. However, since it is often the case that we regret a 
change or make a change incorrectly, the editor provides a u (undo) 
command to reverse the last change which you made. Try this a few 
times, and give it twice in a row to notice that an u also undoes a u. 


The undo command lets you reverse only a single change. After you 
make a number of changes to a line, you may decide that you would 
rather have the original state of the line back. The U command 
restores the current line to the state before you started changing it. 


You can recover text which you delete, even if undo will not bring it 
back; see the section on recovering lost text below. 


3.6 Summary 


SPACE advance the cursor one position 

“H backspace the cursor 

“Ww erase a word during an insert 

erase your erase (usually ~H or #), erases a character during 
an insert 

kill your kill (usually @, ~X, or ~U), kills the insert on this 


12. One subtle point here involves using the / search after ad. This will normally 
delete characters from the current position to the point of the match. If what 
is desired is to delete whole lines including the two points, give the pattern as 
/pat/+0, a line address. 
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line 

repeats the changing command 

opens and inputs new lines, above the current 
undoes the changes you made to the current line 
appends text after the cursor 

changes the object you specify to the following text 
deletes the object you specify 

inserts text before the cursor 

opens and inputs new lines, below the current 
undoes the last change 


co™maer co: 


4. Moving About, Rearranging and 
Duplicating Text 


4.1 Low Level Character Motions 


Now move the cursor to a line where there is a punctuation or a 
bracketing character such as a parenthesis or a comma or period. Try 
the command fx where x is this character. This command finds the 
next x character to the right of the cursor in the current line. Try 
then hitting a ;, which finds the next instance of the same character. 
By using the f command and then a sequence of ;’s you can often get 
to a particular place in a line much faster than with a sequence of 
word motions or SPACEs. There is also a F command, which is like 
f, but searches backward. The ; command repeats F also. 


When you are operating on the text in a line it is often desirable to 
deal with the characters up to, but not including, the first instance of 
a character. Try dfx for some x now and notice that the x character 
is deleted. Undo this with u and then try dtx; the t here stands for 
to, i.e. delete up to the next x, but not the x. The command T is the 
reverse of t. 


When working with the text of a single line, an t moves the cursor to 
the first non-white position on the line, and a $ moves it to the end of 
the line. Thus $a will append new text at the end of the current line. 


Your file may have tab (~I) characters in it. These characters are 
represented as a number of spaces expanding to a tab stop, where tab 
stops are every 8 positions.!* When the cursor is at a tab, it sits on 
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the last of the several spaces which represent that tab. Try moving 
the cursor back and forth over tabs so you understand how this 
works. 


On rare occasions, your file may have nonprinting characters in it. 
These characters are displayed in the same way they are represented 
in this document, that is with a two character code, the first character 
of which is ‘~’. On the screen non-printing characters resemble a ‘~’ 
character adjacent to another, but spacing or backspacing over the 
character will reveal that the two characters are, like the spaces 
representing a tab character, a single character. 


The editor sometimes discards control characters, depending on the 
character and the setting of the beautify option, if you attempt to 
insert them in your file. You can get a control character in the file 
by beginning an insert and then typing a ~V before the control char- 
acter. The ~V quotes the following character, causing it to be 
inserted directly into the file. 


4.2 Higher Level Text Objects 


In working with a document it is often advantageous to work in terms 
of sentences, paragraphs, and sections. The operations ( and ) move 
to the beginning of the previous and next sentences respectively. 
Thus the command d) will delete the rest of the current sentence; 
likewise d( will delete the previous sentence if you are at the begin- 
ning of the current sentence, or the current sentence up to where you 
are if you are not at the beginning of the current sentence. 


either the end of a line, or by two spaces. Any number of closing ‘)’, 
‘), ‘"? and ‘~’ characters may appear after the ‘.’, ‘!’ or ‘?’ before the 
spaces or end of line. 


A sentence is defined to end at a ‘.’, ‘!’ or ‘? which is followed by 


The operations { and } move over paragraphs and the operations [[ 
and ]] move over sections. ! 


13. This is settable by a command of the form :se ts=xCR, where x is 4 to set 
tabstops every four columns. This has effect on the screen representation 
within the editor. 

14. The [f{ and ]] operations require the operation character to be doubled because 
they can move the cursor far from where it currently is. While it is easy to get 
back with the command ~~, these commands would still be frustrating if they 
were easy to hit accidentally. 


4—16 Programmer's Guide: CTIX Supplement 


A paragraph begins after each empty line, and also at each of a set of 
paragraph macros, specified by the pairs of characters in the defini- 
tion of the string valued option paragraphs. The default setting for 
this option defines the paragraph macros of the -ms and —mm macro 
packages, i.e. the ‘.IP’, ‘.LP’, ‘.PP’ and ‘.QP’, ‘.P’ and ‘.LI’ mac- 
ros.!° Each paragraph boundary is also a sentence boundary. The 
sentence and paragraph commands can be given counts to operate 
over groups of sentences and paragraphs. 


Sections in the editor begin after each macro in the sections option, 
normally ‘.NH’, ‘.SH’, ‘.H’ and ‘.HU’, and each line with a 
formfeed ~L in the first column. Section boundaries are always line 
and paragraph boundaries also. 


Try experimenting with the sentence and paragraph commands until! 
you are sure how they work. If you have a large document, try look- 
ing through it using the section commands. The section commands 
interpret a preceding count as a different window size in which to 
redraw the screen at the new location, and this window size is the 
base size for newly drawn windows until another size is specified. 
This is very useful if you are on a slow terminal and are looking for a 
particular section. You can give the first section command a small 
count to then see each successive section heading in a small window. 


4.3 Rearranging and Duplicating Text 


The editor has a single unnamed buffer where the last deleted or 
changed away text is saved, and a set of named buffers a—z which you 
can use to save copies of text and to move text around in your file 
and between files. 


The operator y yanks a copy of the object which follows into the 
unnamed buffer. If preceded by a buffer name, "xy, where x here is 
replaced by a letter a—z, it places the text in the named buffer. The 
text can then be put back in the file with the commands p and P; p 
puts the text after or below the cursor, while P puts the text before or 
above the cursor. 


15. You can easily change or extend this set of macros by assigning a different 
string to the paragraphs option in your EXINIT. See section 6.2 for details. 
The ‘.bp’ directive is also considered to start a paragraph. 
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If the text which you yank forms a part of a line, or is an object such 
as a sentence which partially spans more than one line, then when 
you put the text back, it will be placed after the cursor (or before if 
you use P). If the yanked text forms whole lines, they will be put 
back as whole lines, without changing the current line. In this case, 
the put acts much like a 0 or O command. 


Try the command YP. This makes a copy of the current line and 
leaves you on this copy, which is placed before the current line. The 
command Y is a convenient abbreviation for yy. The command Yp 
will also make a copy of the current line, and place it after the 
current line. You can give Y a count of lines to yank, and thus 
duplicate several lines; try 3YP. 


To move text within the buffer, you need to delete it in one place, 
and put it back in another. You can precede a delete operation by 
the name of a buffer in which the text is to be stored as in "a5dd 
deleting 5 lines into the named buffer a. You can then move the cur- 
sor to the eventual resting place of the these lines and do a "ap or 
"aP to put them back. In fact, you can switch and edit another file 
before you put the lines back, by giving a command of the form :e 
nameCR where name is the name of the other file you want to edit. 
You will have to write back the contents of the current editor buffer 
(or discard them) if you have made changes before the editor will let 
you switch to the other file. An ordinary delete command saves the 
text in the unnamed buffer, so that an ordinary put can move it else- 
where. However, the unnamed buffer is lost when you change files, 
so to move text from one file to another you should use an unnamed 
buffer. 


4.4 Summary 


first non-white on line 

end of line 

forward sentence 

forward paragraph 

forward section 

backward sentence 

backward paragraph 

backward section 

find x forward in line 

put text back, after cursor or below current line 
yank operator, for copies and moves 


Ko PmAT YY wo 
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tx up to x forward, for operators 


Fx f backward in line 
P put text back, before cursor or above current line 
Tx t backward in line 


5. High Level Commands 
5.1 Writing, Quitting, Editing New Files 


So far we have seen how to enter vi and to write out our file using 
either ZZ or :wCR. The first exits from the editor, (writing if changes 
were made), the second writes and stays in the editor. 


If you have changed the editor’s copy of the file but do not wish to 
save your changes, either because you messed up the file or decided 
that the changes are not an improvement to the file, then you can 
give the command :q!CR to quit from the editor without writing the 
changes. You can also reedit the same file (starting over) by giving 
the command :e!CR. These commands should be used only rarely, 
and with caution, as it is not possible to recover the changes you have 
made after you discard them in this manner. 


You can edit a different file without leaving the editor by giving the 
command :e nameCR. If you have not written out your file before 
you try to do this, then the editor will tell you this, and delay editing 
the other file. You can then give the command :wCR to save your 
work and then the :e nameCR command again, or carefully give the 
command :e! nameCR, which edits the other file discarding the 
changes you have made to the current file. To have the editor 
automatically save changes, include set autowrite in your EXINIT, 
and use :n instead of :e. 


5.2 Escaping to a Shell 


You can get to a shell to execute a single command by giving a vi 
command of the form :!cmdCR. The system will run the single com- 
mand cmd and when the command finishes, the editor will ask you to 
hit a RETURN to continue. When you have finished looking at the 
output on the screen, you should hit RETURN and the editor will 
clear the screen and redraw it. You can then continue editing. You 
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can also give another : command when it asks you for a RETURN; in 
this case the screen will not be redrawn. 


If you wish to execute more than one command in the shell, then you 
can give the command :shCR. This will give you a new shell, and 
when you finish with the shell, ending it by typing a ~D, the editor 
will clear the screen and continue. 


On systems which support it, ~Z will suspend the editor and return to 
the (top level) shell. When the editor is resumed, the screen will be 
redrawn. 


5.3 Marking and Returning 


The command ~~ returns to the previous place after a motion of the 
cursor by a command such as /, ? or G. You can also mark lines in 
the file with single letter tags and return to these marks later by nam- 
ing the tags. Try marking the current line with the command mx, 
where you should pick some letter for x, say ‘a’. Then move the cur- 
sor to a different line (any way you like) and hit ~a. The cursor will 
return to the place which you marked. Marks last only until you edit 
another file. 


When using operators such as d and referring to marked lines, it is 
often desirable to delete whole lines rather than deleting to the exact 
position in the line marked by m. In this case you can use the form 
“x rather than ~x. Used without an operator, “x will move to the 
first non-white character of the marked line; similarly ~~ moves to 
the first non-white character of the line containing the previous con- 
text mark ~~. 


5.4 Adjusting the Screen 


If the screen image is messed up because of a transmission error to 
your terminal, or because some program other than the editor wrote 
output to your terminal, you can hit a ~L, the ASCH form-feed char- 
acter, to cause the screen to be refreshed. 


On a dumb terminal, if there are @ lines in the middle of the screen 
as a result of line deletion, you may get rid of these lines by typing 
“R to cause the editor to retype the screen, closing up these holes. 
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Finally, if you wish to place a certain line on the screen at the top 
middle or bottom of the screen, you can position the cursor to that 
line, and then give a z command. You should follow the z command 
with a RETURN if you want the line to appear at the top of the win- 
dow, a. if you want it at the center, or a — if you want it at the bot- 
tom. 


6. Special Topics 


6.1 Editing on Slow Terminals 


When you are on a slow terminal, it is important to limit the amount 
of output which is generated to your screen so that you will not suffer 
long delays, waiting for the screen to be refreshed. We have already 
pointed out how the editor optimizes the updating of the screen dur- 
ing insertions on dumb terminals to limit the delays, and how the edi- 
tor erases lines to @ when they are deleted on dumb terminals. 


The use of the slow terminal insertion mode is controlled by the 
slowopen option. You can force the editor to use this mode even on 
faster terminals by giving the command :se slowCR. If your system is 
sluggish this helps lessen the amount of output coming to your termi- 
nal. You can disable this option by :se noslowCR. 


The editor can simulate an intelligent terminal on a dumb one. Try 
giving the command :se redrawCR. This simulation generates a great 
deal of output and is generally tolerable only on lightly loaded systems 
and fast terminals. You can disable this by giving the command :se 
noredrawCr. 


The editor also makes editing more pleasant at low speed by starting 
editing in a small window, and letting the window expand as you edit. 
This works particularly well on intelligent terminals. The editor can 
expand the window easily when you insert in the middle of the screen 
on these terminals. If possible, try the editor on an intelligent termi- 
nal to see how this works. 


You can control the size of the window which is redrawn each time 
the screen is cleared by giving window sizes as argument to the com- 
mands which cause large screen motions: 


Ws / bl [L 1] ~ “uw 


Thus if you are searching for a particular instance of a common string 
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in a file you can precede the first search command by a small 
number, say 3, and the editor will draw three line windows around 
each instance of the string which it locates. 


You can easily expand or contract the window, placing the current 
line as you choose, by giving a number on a z command, after the z 
and before the following RETURN, . or -. Thus the command 25. 
redraws the screen with the current line in the center of a five line 
window. !® 


If the editor is redrawing or otherwise updating large portions of the 
display, you can interrupt this updating by hitting a DEL or RUB as 
usual. If you do this you may partially confuse the editor about what 
is displayed on the screen. You can still edit the text on the screen if 
you wish; clear up the confusion by hitting a ~L; or move or search 
again, ignoring the current state of the display. 


See section 8.8 on open mode for another way to use the vi command 
set on slow terminals. 


6.2 Options, Set, and Editor Startup Files 


The editor has a set of options, some of which have been mentioned 
above. The most useful options are given in the following table. 


16. Note that the command Sz. has an entirely different effect, placing line 5 in the 
center of a new window. 
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Name Default Description 


autoindent _noai Supply indentation automatically 
autowrite noaw Automatic write before :n, :ta, ~t,! 
ignorecase  noic Ignore case in searching 
lisp nolisp ( € ) } commands deal with S- 
expressions 
list nolist Tabs print as ~I; end of lines marked 
with $ 
magic nomagic The characters . [ and * are special in 
scans 
number nonu Lines are displayed prefixed with line 
numbers 
paragraphs para= Macro names which start paragraphs 
IPLPPPQPbpP 
LI 
redraw nore Simulate a smart terminal on a dumb 
one 
sections sect= Macro names which start new sections 
NHSHH HU 
shiftwidth sw=8 Shift distance for <, > and input ~D 
and ~T 
showmatch nosm Show matching ( or { as ) or } is 
typed 
slowopen slow Postpone display updates during 
inserts 
term dumb The kind of terminal you are using 


The options are of three kinds: numeric options, string options, and 
toggle options. You can set numeric and string options by a state- 
ment of the form 


set opt=val 


and toggle options can be set or unset by statements of one of the 
forms 


set opt 
set noopt 


These statements can be placed in your EXINIT in your environ- 
ment, or given while you are running vi by preceding them with a: 
and following them with a CR. 


You can get a list of all options which you have changed by the com- 
mand :setCR, or the value of a single option by the command :set 
opt?CR. A list of all possible options and their values is generated by 
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zset allCR. Set can be abbreviated se. Multiple options can be placed 
on one line, e.g. :se ai aw nuCR. 


Options set by the set command only last while you stay in the editor. 
It is common to want to have certain options set whenever you use 
the editor. This can be accomplished by creating a list of ex com- 
mands!’ which are to be run every time you start up ex, edit, or vi. 
A typical list includes a set command, and possibly a few map com- 
mands. Since it is advisable to get these commands on one line, they 
can be separated with the | character, for example: 


set ai aw terse| map @ dd| map # x 


which sets the options autoindent, autowrite, terse, (the set command), 
makes @ delete a line, (the first map), and makes # delete a charac- 
ter, (the second map). (See section 6.9 for a description of the map 
command) This string should be placed in the variable EXINIT in 
your environment. If you use the shell csh, put this line in the file 
.fogin in your home directory: 


setenv EXINIT “set ai aw terse | map @ dd| map # x~ 


If you use the standard shell sh, put these lines in the file .profile in 
your home directory: 


EXINIT= ‘set ai aw terse| map @ dd! map # x* 
export EXINIT 


Of course, the particulars of the line would depend on which options 
you wanted to set. 


6.3 Recovering Lost Lines 


You might have a serious problem if you delete a number of lines and 
then regret that they were deleted. Despair not, the editor saves the 
last 9 deleted blocks of text in a set of numbered registers 1-9. You 
can get the n’th previous deleted text back in your file by the com- 
mand "np. The " here says that a buffer name is to follow, n is the 
number of the buffer you wish to try (use the number 1 for now), 
and p is the put command, which puts text in the buffer after the cur- 
sor. If this doesn’t bring back the text you wanted, hit u to undo this 


17. All commands which start with : are ex commands. 
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and then . (period) to repeat the put command. In general the . 
command will repeat the last change you made. As a special case, 
when the last command refers to a numbered text buffer, the . com- 
mand increments the number of the buffer before repeating the com- 
mand. Thus a sequence of the form 


"1pu.u.u. 


will, if repeated long enough, show you all the deleted text which has 
been saved for you. You can omit the u commands here to gather up 
all this text in the buffer, or stop after any . command to keep just 
the then recovered text. The command P can also be used rather 
than p to put the recovered text before rather than after the cursor. 


6.4 Recovering Lost Files 


If the system crashes, you can recover the work you were doing to 
within a few changes. You will normally receive mail when you next 
login giving you the name of the file which has been saved for you. 
You should then change to the directory where you were when the 
system crashed and give a command of the form: 


% vi -r name 


replacing name with the name of the file which you were editing. 
This will recover your work to a point near where you left off.!® 


You can get a listing of the files which are saved for you by giving the 
command: 


% vi-r 


If there is more than one instance of a particular file saved, the editor 
gives you the newest instance each time you recover it. You can thus 
get an older saved copy back by first recovering the newer copies. 


For this feature to work, vi must be correctly installed by a super user 
on your system, and the mail program must exist to receive mail. 


18. In rare cases, some of the lines of the file may be lost. The editor will give you 
the numbers of these lines and the text of the lines will be replaced by the 
string ““LOST’’. These lines will almost always be among the last few which 
you changed. You can either choose to discard the changes which you made 
(if they are easy to remake) or to replace the few lost lines by hand. 
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The invocation ‘‘vi -r’ will not always list all saved files, but they can 
be recovered even if they are not listed. 


6.5 Continuous Text Input 


When you are typing in large amounts of text it is convenient to have 
lines broken near the right margin automatically. You can cause this 
to happen by giving the command :se wm=10CR. This causes all 
lines to be broken at a space at least 10 columns from the right hand 
edge of the screen. 


If the editor breaks an input line and you wish to put it back together 
you can tell it to join the lines with J. You can give J a count of the 
number of lines to be joined as in 3J to join 3 lines. The editor sup- 
plies white space, if appropriate, at the juncture of the joined lines, 
and leaves the cursor at this white space. You can kill the white 
space with x if you don’t want it. 


6.6 Features for Editing Programs 


The editor has a number of commands for editing programs. The 
thing that most distinguishes editing of programs from editing of text 
is the desirability of maintaining an indented structure to the body of 
the program. The editor has a autoindent facility for helping you gen- 
erate correctly indented programs. 


To enable this facility you can give the command :se aiCR. Now try 
opening a new line with o and type some characters on the line after a 
few tabs. If you now start another line, notice that the editor sup- 
plies white space at the beginning of the line to line it up with the 
previous line. You cannot backspace over this indentation, but you 
can use ~D key to backtab over the supplied indentation. 


Each time you type ~D you back up one position, normally to an 8 
column boundary. This amount is settable; the editor has an option 
called shifrwidth which you can set to change this value. Try giving 
the command :se sw=4CR and then experimenting with autoindent 
again. 


For shifting lines in the program left and right, there are operators < 
and >. These shift the lines you specify right or left by one 
shiftwidth. Try << and >> which shift one line left or right, and <L 
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and >L shifting the rest of the display left and right. 


If you have a complicated expression and wish to see how the 
parentheses match, put the cursor at a left or right parenthesis and hit 
%. This will show you the matching parenthesis. This works also for 
braces { and }, and brackets [| and }. 


If you are editing C programs, you can use the [[{ and ]] keys to 
advance or retreat to a line starting with a {, i.e. a function declara- 
tion at a time. When J] is used with an operator it stops after a line 
which starts with }; this is sometimes useful with y]}. 


6.7 Filtering Portions of the Buffer 


You can run system commands over portions of the buffer using the 
operator !. You can use this to sort lines in the buffer, or to refor- 
mat portions of the buffer with a pretty-printer. Try typing in a list 
of random words, one per line and ending them with a blank line. 
Back up to the beginning of the list, and then give the command 
!}sortCR. This says to sort the next paragraph of material, and the 
blank line ends a paragraph. 


6.8 Commands for Editing LISP 


If you are editing a LISP program you should set the option lisp by 
doing :se lispCR. This changes the ( and ) commands to move back- 
ward and forward over s-expressions. The { and } commands are 
like ( and ) but don’t stop at atoms. These can be used to skip to the 
next list, or through a comment quickly. 


The autoindent option works differently for LISP, supplying indent to 
align at the first argument to the last open list. If there is no such 
argument then the indent is two spaces more than the last level. 


There is another option which is useful for typing in LISP, the 
showmatch option. Try setting it with :se smCR and then try typing a 
‘( some words and then a ‘)’. Notice that the cursor shows the posi- 
tion of the ‘(’ which matches the ‘)’ briefly. This happens only if the 
matching ‘(’ is on the screen, and the cursor stays there for at most 
one second. 


The editor also has an operator to realign existing lines as though 
they had been typed in with lisp and autoindent set. This is the = 
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operator. Try the command =% at the beginning of a function. This 
will realign all the lines of the function declaration. 


When you are editing LISP,, the [[ and ]] advance and retreat to lines 
beginning with a (, and are useful for dealing with entire function 
definitions. 


6.9 Macros 


Vi has a parameterless macro facility, which lets you set it up so that 
when you hit a single keystroke, the editor will act as though you had 
hit some longer sequence of keys. You can set this up if you find 
yourself typing the same sequence of commands repeatedly. 


Briefly, there are two flavors of macros: 


a) Ones where you put the macro body in a buffer register, say x. 
You can then type @x to invoke the macro. The @ may be fol- 
lowed by another @ to repeat the last macro. 


b) You can use the map command from wi (typically in your 
EXINIT ) with a command of the form: 


:map ths rhsCR 


mapping /As into rhs. There are restrictions: fis should be one 
keystroke (either 1 character or one function key) since it must 
be entered within one second (unless notimeout is set, in which 
case you can type it as slowly as you wish, and vi will wait for 
you to finish it before it echoes anything). The /ks can be no 
longer than 10 characters, the rhs no longer than 100. To get a 
space, tab or newline into /As or rhs you should escape them 
with a ~V. (It may be necessary to double the ~V if the map 
command is given inside wi, rather than in ex.) Spaces and tabs 
inside the rhs need not be escaped. 


Thus to make the q key write and exit the editor, you can give the 
command 


:map q :wq7 V7 VCR CR 


which means that whenever you type q, it will be as though you had 
typed the four characters ;:wqCR. A “~V’s is needed because without 
it the CR would end the : command, rather than becoming part of the 
map definition. There are two ~V’s because from within wi, two ~ V's 
must be typed to get one. The first CR is part of the rhs, the second 
terminates the : command. 
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Macros can be deleted with 


unmap lhs 


If the /hs of a macro is “#0” through “‘#9’’, this maps the particular 
function key instead of the 2 character ‘‘#’’ sequence. So that termi- 
nals without function keys can access such definitions, the form ‘‘#x’”’ 
will mean function key x on all terminals (and need not be typed 
within one second.) The character ‘‘#’’ can be changed by using a 
macro in the usual way: 


imap “V°V"1l# 


to use tab, for example. (This won’t affect the map command, which 
still uses #, but just the invocation from visual mode. 


The undo command reverses an entire macro call as a unit, if it made 
any changes. 


Placing a ‘!’ after the word map causes the mapping to apply to input 
mode, rather than command mode. Thus, to arrange for ~T to be 
the same as 4 spaces in input mode, you can type: 


‘map ~T ~Vbbbb 


where b is a blank. The ~V is necessary to prevent the blanks from 
being taken as white space between the /hs and rhs. 


7. Word Abbreviations 


A feature similar to macros in input mode is word abbreviation. This 
allows you to type a short word and have it expanded into a longer 
word or words. The commands are :abbreviate and :unabbreviate 
(:ab and :una) and have the same syntax as :map. For example: 


‘ab eecs Electrical Engineering and Computer Sciences 


causes the word “‘eecs’’ to always be changed into the phrase ‘‘Electri- 
cal Engineering and Computer Sciences’. Word abbreviation is dif- 
ferent from macros in that only whole words are affected. If ‘‘eecs” 
were typed as part of a larger word, it would be left alone. Also, the 
partial word is echoed as it is typed. There is no need for an abbrevi- 
ation to be a single keystroke, as it should be with a macro. 
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7.1 Abbreviations 


The editor has a number of short commands which abbreviate longer 
commands which we have introduced here. You can find these com- 
mands easily on the quick reference card. They often save a bit of 
typing and you can learn them as convenient. 


8. Nitty-gritty Details 
8.1 Line Representation in the Display 


The editor folds long logical lines onto many physical lines in the 
display. Commands which advance lines advance logical lines and 
will skip over all the segments of a line in one motion. The com- 
mand | moves the cursor to a specific column, and may be useful for 
getting near the middle of a long line to split it in half. Try 801 ona 
line which is more than 80 columns long. ! 


The editor only puts full lines on the display; if there is not enough 
room on the display to fit a logical line, the editor leaves the physical 
line empty, placing only an © on the line as a place holder. When 
you delete lines on a dumb terminal, the editor will often just clear 
the lines to @ to save time (rather than rewriting the rest of the 
screen.) You can always maximize the information on the screen by 
giving the ~R command. 


If you wish, you can have the editor place line numbers before each 
line on the display. Give the command :se nuCR to enable this, and 
the command :se nonuCR to turn it off. You can have tabs 
represented as ~I and the ends of lines indicated with ‘$’ by giving 
the command :se listCR; :se nolistCR turns this off. 

Finally, lines consisting of only the character ‘~’ are displayed when 
the last line in the file is in the middle of the screen. These represent 
physical lines which are past the logical end of file. 


19. You can make long lines very easily by using J to join together short lines. 
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8.2 Counts 


Most vi commands will use a preceding count to affect their behavior 
in some way. The following table gives the common ways in which 
the counts are used: 


new window size :/? TW] ° 7” 
scroll amount “-D -U 
line/column number z G | 

repeat effect most of the rest 


The editor maintains a notion of the current default window size. On 
terminals which run at speeds greater than 1200 baud the editor uses 
the full terminal screen. On terminals which are slower than 1200 
baud (most dialup lines are in this group) the editor uses 8 lines as 
the default window size. At 1200 baud the default is 16 lines. 


This size is the size used when the editor clears and refills the screen 
after a search or other motion moves far from the edge of the current 
window. The commands which take a new window size as count all 
often cause the screen to be redrawn. If you anticipate this, but do 
not need as large a window as you are currently using, you may wish 
to change the screen size by specifying the new size before these com- 
mands. In any case, the number of lines used on the screen will 
expand if you move off the top with a - or similar command or off 
the bottom with a command such as RETURN or ~D. The window 
will revert to the last specified size the next time it is cleared and 
refilled.?° 


The scroll commands ~D and *U likewise remember the amount of 
scroll last specified, using half the basic window size initially. The 
simple insert commands use a count to specify a repetition of the 
inserted text. Thus 80a+----ESC will insert a grid-like string of text. 
A few commands also use a preceding count as a line or column 
number. 


Except for a few commands which ignore any counts (such as ~R), 
the rest of the editor commands use a count to indicate a simple 
repetition of their effect. Thus 5w advances five words on the 
current line, while S5RETURN advances five lines. A very useful 
instance of a count as a repetition is a count given to the . command, 


20. But not by a ~L which just redraws the screen as it is. 
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which repeats the last changing command. If you do dw and then 3., 
you will delete first one and then three words. You can then delete 
two more words with 2.. 


8.3 More File Manipulation Commands 


The following teble lists the file manipulation commands which you 
can use when vou te ini 


Ww wot Bock statins 
2WwG +. eee aes 1 i & vt 
IX vet ard auit (same as ZZ). 


Te Name 
:e! 


changes 


ter amy wuriinyg at dad 

2@ 43; weit SPartiss at Une a 

ie # eeit 

TW oie MRE? Tihs Get 

PW Noite AL ATELD Pat enrur 

DALY Wott epee ag ae OP Ae 
Hae ateran te ea Psa her eee SAE OP EPhes 

or tom Pood Gutpai of ceed onto buffer 
n cuit dieat ite in argument list 

int weit next tiie. discarding changes to current 
mares epyerf. mew argument Itst 

sla fag cbt tac containiag tag fag, at fog 


All of these corenoaints are 


{bs a CR or ESC. The most basic 
commands aie oe ert ce AN normal editing session on a single file 
will end with a 74 cuemend if > editing for a long period of 
time vou van ifter major amounts of 
editing, unc Vici Sou edit more than one 
file, you van fi oh. will ai ise athe start editing a new file by 
BIVINg 4 te COMM, GF sof cutee Gad use in <file>, 


If you make changes to the editer’s copy of a file, but do not wish to 
write them back. then vou must give an ? after the command you 
would otherwis 
have mace. Use 


The :e command cen fx given a + argument to start at the end of the 


file, or a +4 Grgumemt to Start at iine nm. In actuality, 1 may be any 
editor command not cominiminy a snuce, usefully a scan like +/pat or 
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+?pat. In forming new names to the e command, you can use the 
character % which is replaced by the current file name, or the charac- 
ter # which is replaced by the alternate file name. The alternate file 
name is generally the last name you typed other than the current file. 
Thus if you try to do a :e and get a diagnostic that you haven’t writ- 
ten the file, you can give a :w command and then a :e # command to 
redo the previous :e. 


You can write part of the buffer to a file by finding out the lines that 
bound the range to be written using ~G, and giving these numbers 
after the : and before the w, separated by ,’s. You can also mark 
these lines with m and then use an address of the form “x, “y on the 
w command here. 


You can read another file into the buffer after the current line by 
using the :r command. You can similarly read in the output from a 
command, just use !cmd instead of a file name. 


If you wish to edit a set of files in succession, you can give all the 
names on the command line, and then edit each one in turn using the 
command in. It is also possible to respecify the list of files to be 
edited by giving the :n command a list of file names, or a pattern to 
be expanded as you would have given it on the initial vi command. 


If you are editing large programs, you will find the :ta command very 
useful. It utilizes a data base of function names and their locations, 
which can be created by programs such as crags, to quickly find a 
function whose name you give. If the :ta command will require the 
editor to switch files, then you must :w or abandon any changes 
before switching. You can repeat the :ta command without any argu- 
ments to look for the same tag again. 


8.4 More About Searching for Strings 


When you are searching for strings in the file with / and ?, the editor 
normally places you at the next or previous occurrence of the string. 
If you are using an operator such as d, ¢ or y, then you may well 
wish to affect lines up to the line before the line containing the pat- 
tern. You can give a search of the form /par/—n to refer to the wth 
line before the next line containing par, or you can use + instead of — 
to refer to the lines after the one containing par. If you don't give a 
line offset, then the editor will affect characters up to the match 
place, rather than whole lines; thus use ‘‘+0” to affect to the line 
which matches. 
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You can have the editor ignore the case of words in the searches it 
does by giving the command :se icCR. The command :se noicCR 
turns this off. 


Strings given to searches may actually be regular expressions. If you 
do not want or need this facility, you should 


set nomagic 


in your EXINIT. In this case, only the characters t and $ are special 
in patterns. The character \ is also then special (as it is most every- 
where in the system), and may be used to get at the an extended pat- 
tern matching facility. It is also necessary to use a \ before a/ ina 
forward scan or a ? in a backward scan, in any case. The following 
table gives the extended forms when magic is set. 


t at beginning of pattern, matches beginning of line 
$ at end of pattern, matches end of line 

, matches any character 

\< matches the beginning of a word 

\> matches the end of a word 

[ser] matches any single character in str 


{tstr] | matches any single character not in s¢r 
[x-y] | matches any character between x and y 
= matches any number of the preceding pattern 


If you use nomagic mode, then the . [ and * primitives are given with 
a preceding \. 


8.5 More About Input Mode 


There are a number of characters which you can use to make correc- 
tions during input mode. These are summarized in the following 
table. 


“H deletes the last input character 
“Ww deletes the last input word, defined as by b 
erase your erase character, same as ~H 


kill your kill character, deletes the input on this line 
\ escapes a following ~H and your erase and kill 
ESC ends an insertion 

DEL interrupts an insertion, terminating it abnormally 
CR starts a new line 

“D backtabs over autoindent 


4—34 Programmer's Guide: CTIX Supplement 


0-D kills all the autoindent 
t*D same as 07D, but restores indent next line 
“Vv quotes the next non-printing character into the file 


The most usual way of making corrections to input is by typing ~H to 
correct a single character, or by typing one or more ~W’'s to back 
over incorrect words. If you use # as your erase character in the nor- 
mal system, it will work like ~H. 


Your system kill character, normally @, ~X or *U, will erase all the 
input you have given on the current line. In general, you can neither 
erase input back around a line boundary nor can you erase characters 
which you did not insert with this insertion command. To make 
corrections on the previous line after a new line has been started you 
can hit ESC to end the insertion, move over and make the correction, 
and then return to where you were to continue. The command A 
which appends at the end of the current line is often useful for con- 
tinuing. 


If you wish to type in your erase or kill character (say # or @) then 
you must precede it with a \, just as you would do at the normal sys- 
tem command level. A more general way of typing non-printing 
characters into the file is to precede them with a ~V. The ~V echoes 
as a t character on which the cursor rests. This indicates that the edi- 
tor expects you to type a control character. In fact you may type any 
character and it will be inserted into the file at that point.7! 


If you are using autoindent you can backtab over the indent which it 
supplies by typing a ~D. This backs up to a shiftwidth boundary. 
This only works immediately after the supplied auroindent. 


When you are using autoindent you may wish to place a label at the 
left margin of a line. The way to do this easily is to type t and then 
“D. The editor will move the cursor to the left margin for one line, 


21. This is not quite true. The implementation of the editor does not allow the 
NULL (*@) character to appear in files. Also the LF (linefeed or ~J) character 
is used by the editor to separate lines in the file, so it cannot appear in the 
middle of a line. You can insert any other character, however, if you wait for 
the editor to echo the + before you type the character. In fact, the editor will 
treat a following letter as a request for the corresponding control character. 
This is the only way to type ~S or ~Q, since the system normally uses them to 
suspend and resume output and never gives them to the editor to process. 
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and restore the previous indent on the next. You can also type a 0 
followed immediately by a ~D if you wish to kill all the indent and 
not have it come back on the next line. 


8.6 Upper Case Only Terminals 


If your terminal has only upper case, you can still use vi by using the 
normal system convention for typing on such a terminal. Characters 
which you normally type are converted to lower case, and you can 
type upper case letters by preceding them with a \. The characters { 
~ } | > are not available on such terminals, but you can escape them 
as \( \t \) \! \~. These characters are represented on the display 
in the same way they are typed.7? 


8.7 Vi and Ex 


Vi is actually one mode of editing within the editor ex. When you 
are running vi you can escape to the line oriented editor of ex by giv- 
ing the command Q. All of the : commands which were introduced 
above are available in ex. Likewise, most ex commands can be 
invoked from vi using :. Just give them without the : and follow 
them with a CR. 


In rare instances, an internal error may occur in vi. In this case you 
will get a diagnostic and be left in the command mode of ex. You 
can then save your work and quit if you wish by giving a command x 
after the : which ex prompts you with, or you can reenter vi by giving 
ex a vi command. 


There are a number of things which you can do more easily in ex 
than in wi. Systematic changes in line oriented material are particu- 
larly easy. You can read the advanced editing documents for the edi- 
tor ed to find out a lot more about this style of editing. Experienced 
users often mix their use of ex command mode and vi command 
mode to speed the work they are doing. 


22. The \ character you give will not echo until you type another key. 
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8.8 Open Mode: Vi on Hardcopy Terminals and 
“glass tty’s” 


If you are on a hardcopy terminal or a terminal which does not have 
a cursor which can move off the bottom line, you can still use the 
command set of vi, but in a different mode. When you give a vi 
command, the editor will tell you that it is using open mode. This 
name comes from the open command in ex, which is used to get into 
the same mode. 


The only difference between visual mode and open mode is the way in 
which the text is displayed. 


In open mode the editor uses a single line window into the file, and 
moving backward and forward in the file causes new lines to be 
displayed, always below the current line. Two commands of vi work 
differently in open: z and ~R. The z command does not take 
parameters, but rather draws a window of context around the current 
line and then returns you to the current line. 


If you are on a hardcopy terminal, the ~R command will retype the 
current line. On such terminals, the editor normally uses two lines to 
represent the current line. The first line is a copy of the line as you 
started to edit it, and you work on the line below this line. When 
you delete characters, the editor types a number of \’s to show you 
the characters which are deleted. The editor also reprints the current 
line soon after such changes so that you can see what the line looks 
like again. 


It is sometimes useful to use this mode on very slow terminals which 
can support vi in the full screen mode. You can do this by entering 
ex and using an open command. 
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Appendix: Character Functions 


This appendix gives the uses the editor makes of each character. The 
characters are presented in their order in the ASCII character set: 
Control characters come first, then most special characters, then the 
digits, upper and then lower case characters. 


For each character we tell a meaning it has as a command and any 
meaning it has during an insert. If it has only meaning as a com- 
mand, then only this is discussed. Section numbers in parentheses 
indicate where the character is discussed; a ‘f’ after the section 
number means that the character is mentioned in a footnote. 


a) 


“A 
“B 


aC 
“D 


“E 


~H (BS) 


Not a command character. If typed as the first character 
of an insertion it is replaced with the last text inserted, 
and the insert terminates. Only 128 characters are saved 
from the last insert; if more characters were inserted the 
mechanism is not available. A ~@ cannot be part of the 
file due to the editor implementation (8.5f). 


Unused. 


Backward window. A count specifies repetition. Two 
lines of continuity are kept if possible (2.1, 7.1, 8.2). 


Unused. 


As a command, scrolls down a half-window of text. A 
count gives the number of (logical) lines to scroll, and is 
remembered for future ~D and ~U commands (2.1, 8.2). 
During an insert, backtabs over autoindent white space at 
the beginning of a line (6.6, 8.5); this white space cannot 
be backspaced over. 


Exposes one more line below the current screen in the 
file, leaving the cursor where it is if possible. (Version 3 


only.) 


Forward window. A count specifies repetition. Two 
lines of continuity are kept if possible (2.1, 7.1, 8.2). 


Equivalent to :fCR, printing the current file, whether it 
has been modified, the current line number and the 
number of lines in the file, and the percentage of the way 
through the file that you are. 


Same as left arrow. (See h). During an insert, eliminates 
the last input character, backing over it but not erasing it; 
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~I(TAB) 


~M(CR) 


“N 
-O 
-P 
“Q 


“R 


it remains so you can see what you typed if you wish to 
type something only slightly different (2.4, 8.5). 


Not a command character. When inserted it prints as 
some number of spaces. When the cursor is at a tab char- 
acter it rests at the last of the spaces which represent the 
tab. The spacing of tabstops is controlled by the tabstop 
option (4.1, 6.2). 


Same as down arrow (see j). 
Unused. 


The ASCII formfeed character, this causes the screen to be 
cleared and redrawn. This is useful after a transmission 
error, if characters typed by a program other than the edi- 
tor scramble the screen, or after output is stopped by an 
interrupt (5.4, 8.2f). 


A carriage return advances to the next line, at the first 
non-white position in the line. Given a count, it advances 
that many lines. During an insert, a CR causes the insert 
to continue onto another line. 


Same as down arrow (see j). 
Unused. 
Same as up arrow (see k). 


Not a command character. In input mode, ~Q quotes the 
next character, the same as ~V, except that some teletype 
drivers will eat the ~Q so that the editor never sees it. 


Redraws the current screen, eliminating logical lines not 
corresponding to physical lines (lines with only a single © 
character on them). On hardcopy terminals in open 
mode, retypes the current line (5.4, 8.1, 8.8). 


Unused. Some teletype drivers use ~S to suspend output 
until ~Q is pressed. 


Not a command character. During an insert, with auroin- 
dent set and at the beginning of the line, inserts shiftwidth 
white space. 


Scrolls the screen up, inverting ~D which scrolls down. 
Counts work as they do for ~D, and the previous scroll 
amount is common to both. On a dumb terminal, ~U 
will often necessitate clearing and redrawing the screen 
further back in the file (2.1, 8.2). 
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“Vv Not a command character. In input mode, quotes the 
next character so that it is possible to insert non-printing 
and special characters into the file (6.9, 8.5). 


“WwW Not a command character. During an insert, backs up as 
b would in command mode; the deleted characters remain 
on the display (see ~H) (8.5). 


“x Unused. 


7x Exposes one more line above the current screen, leaving 
the cursor where it is if possible. (No mnemonic value for 
this key; however, it is next to ~U which scrolls up a 
bunch.) (Version 3 only.) 


“Z If supported by the Unix system, stops the editor, exiting 
to the top level shell. Same as :stopCR. Othenvise, 
unused. 


“[ (ESC) Cancels a partially formed command, such as a z when no 
following character has yet been given; terminates inputs 
on the last line (read by commands such as : / and ?); 
ends insertions of new text into the buffer. If an ESC is 
given when quiescent in command state, the editor rings 
the bell or flashes the screen. You can thus hit ESC if you 
don’t know what is happening till the editor rings the bell. 
Tf you don’t know if you are in insert mode you can type 
ESCa, and then material to be input; the material will be 
inserted correctly whether or not you were in insert mode 
when you started (1.6, 3.1, 8.5). 


TN Unused. 


~] Searches for the word which is after the cursor as a tag. 
Equivalent to typing :ta, this word, and then a CR. 
Mnemonically, this command ts “go right to” (8.3). 


“t Equivalent to :e #CR, returning to the previous position 
in the last edited file, or editing a file which you specified 
if you got a ‘No write since last change diagnostic’ and 
do not want to have to type the file name again (8.3). 
(You have to do a :w before ~t will work in this case. If 
you do not wish to write the file you should do :e! #CR 
instead.) 


a Unused. Reserved as the command character for the 
Tektronix 4025 and 4027 terminal. 
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SPACE Same as right arrow (see 1). 


! An operator, which processes lines from the buffer with 
reformatting commands. Follow ! with the object to be 
processed, and then the command name terminated by 
CR. Doubling ! and preceding it by a count causes count 
lines to be filtered; otherwise the count is passed on to the 
object after the !. Thus 2!}|fmrCR reformats the next 
two paragraphs by running them through the program fir. 
If you are working on LISP, the command !% grindCR,”? 
given at the beginning of a function, will run the text of 
the function through the LISP grinder (6.7, 8.3). To read 
a file or the output of a command into the buffer use :r 
(8.3). To simply execute a command use :! (8.3). 


' Precedes a named buffer specification. There are named 
buffers 1-9 used for saving deleted text and named 
buffers a—z into which you can place text (4.3, 6.3) 


# The macro character which, when followed by a number, 
will substitute for a function key on terminals without 
function keys (6.9). In input mode, if this is your erase 
character, it will delete the last character you typed in 
input mode, and must be preceded with a \ to insert it, 
since it normally backs over the last input character you 
gave. 


$ Moves to the end of the current line. If you :se listCR, 
then the end of each line will be shown by printing a $ 
after the end of the displayed text in the line. Given a 
count, advances to the count’th following end of line; thus 
2$ advances to the end of the following line. 


% Moves to the parenthesis or brace { } which balances the 
parenthesis or brace at the current cursor position. 

& A synonym for :&CR, by analogy with the ex & com- 
mand. 


When followed by a ~ returns to the previous context at 
the beginning of a line. The previous context is set when- 
ever the current line is moved in a non-relative way. 


23. Both fmt and grind are Berkeley programs and may not be present at all 
installations. 
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When followed by a letter a—z, returns to the line which 
was marked with this letter with a m command, at the 
first non-white character in the line. (2.2, 5.3). When 
used with an operator such as d, the operation takes place 
over complete lines; if you use ~, the operation takes 
place from the exact marked place to the current cursor 
position within the line. 


( Retreats to the beginning of a sentence, or to the begin- 
ning of a LISP s-expression if the /isp option is set. A sen- 
tence ends at a. ! or ? which is followed by cither the end 
of a line or by two spaces. Any number of closing ) } " 
and ~ characters may appear after the . ! or ?, and before 
the spaces or end of line. Sentences also begin at para- 
graph and section boundaries (see { and [[ below). A 
count advances that many sentences (4.2, 6.8). 


) Advances to the beginning of a sentence. A count repeats 
the effect. See ( above for the definition of a sentence 
(4.2, 6.8). 

. Unused. 

+ Same as CR when used as a command. 

; Reverse of the last f F t or T command, looking the other 


way in the current line. Especially useful after hitting too 
many ; characters. A count repeats the search. 


- Retreats to the previous line at the first non-white charac- 
ter. This is the inverse of + and RETURN. If the line 
moved to is not on the screen, the screen 15 scrolled, or 
cleared and redrawn if this is not possible. If a large 
amount of scrolling would be required the screen is also 
cleared and redrawn, with the current line at the center 


(2.3). 


Repeats the last command which changed the buffer. 
Especially useful when deleting words or lines; you can 
delete some words/lines and then hit . to delete more and 
more words/lines. Given a count, it passes it on to the 
command being repeated. Thus after a 2dw, 3. deletes 
three words (3.3, 6.3, 8.2, 8.4). 


/ Reads a string from the last line on the screen, and scans 
forward for the next occurrence of this string. The nor- 
mal input editing sequences may be used during the input 
on the bottom line; an returns to command state without 
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1-9 


ever searching. The search begins when you hit CR to ter- 
minate the pattern; the cursor moves to the beginning of 
the last line to indicate that the search is in progress; the 
search may then be terminated with a DEL or RUB, or by 
backspacing when at the beginning of the bottom line, 
returning the cursor to its initial position. Searches nor- 
mally wrap end-around to find a string anywhere in the 
buffer. 


When used with an operator the enclosed region is nor- 
mally affected. By mentioning an offset from the line 
matched by the pattern you can force whole lines to be 
affected. To do this give a pattern with a closing a clos- 
ing / and then an offset +n or -n. 


To include the character / in the search string, you must 
escape it with a preceding \. A t at the beginning of the 
pattern forces the match to occur at the beginning of a 
line only; this speeds the search. A $ at the end of the 
pattern forces the match to occur at the end of a line 
only. More extended pattern matching is available, see 
section 7.4; unless you set nomagic in your .exrc file you 
will have to preceed the characters . [ * and ~ in the 
search pattern with a \ to get them to work as you would 
naively expect (1.6, 2.2, 6.1, 8.2, 8.4). 


Moves to the first character on the current line. Also 
used, in forming numbers, after an initial 1-9. 


Used to form numeric arguments to commands (2.3, 8.2). 


A prefix to a set of commands for file and option manipu- 
lation and escapes to the system. Input is given on the 
bottom line and terminated with an CR, and the command 
then executed. You can return to where you were by hit- 
ting DEL or RUB if you hit : accidentally (see primarily 
6.2 and 8.3). 


Repeats the last single character find which used f F t or 
T. A count iterates the basic scan (4.1). 


An operator which shifts lines left one shiftwidth, nor- 
mally 8 spaces. Like all operators, affects lines when 
repeated, as in <<. Counts are passed through to the 
basic object, thus 3<< shifts three lines (6.6, 8.2). 


Reindents line for LISP, as though they were typed in with 
lisp and autoindent set (6.8). 
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> An operator which shifts lines right one shiftwidth, nor- 
mally 8 spaces. Affects lines when repeated as in >>. 
Counts repeat the basic object (6.6, 8.2). 


es Scans backwards, the opposite of /. See the / description 
above for details on scanning (2.2, 6.1, 8.4). 


@ A macro character (6.9). If this is your kill character, 
you must escape it with a \ to type it in during input 
mode, as it normally backs over the input you have given 
on the current line (3.1, 3.4, 8.5). 


Appends at the end of line, a synonym for $a (8.2). 


B Backs up a word, where words are composed of non- 
blank sequences, placing the cursor at the beginning of 
the word. A count repeats the effect (2.4). 


C Changes the rest of the text on the current line; a 
synonym for c$. 

D Deletes the rest of the text on the current line; a synonym 
for d$. 

E Moves forward to the end of a word, defined as blanks 
and non-blanks, like B and W. A count repeats the 
effect. 

F Finds a single following character, backwards in the 
current line. A count repeats this search that many times 
(4.1). 

G Goes to the line number given as preceding argument, or 


the end of the file if mo preceding count is given. The 
screen is redrawn with the new current line in the center 
if necessary (2.2). 


H Home arrow. Homes the cursor to the top line on the 
screen. If a count is given, then the cursor is moved to 
the count’th line on the screen. In any case the cursor is 
moved to the first non-white character on the line. If 
used as the target of an operator, full lines are affected 


(2.3, 3.2). 
I Inserts at the beginning of a line; a synonym for ti. 
J Joins together lines, supplying appropriate white space: 


one space between words, two spaces after a ., and no 
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spaces at all if the first character of the joined on line is ). 
A count causes that many lines to be joined rather than 
the default two (6.5, 8.1f). 


Unused. 


Moves the cursor to the first non-white character of the 
last line on the screen. With a count, to the first non- 
white of the count’th line from the bottom. Operators 
affect whole lines when used with L (2.3). 


Moves the cursor to the middle line on the screen, at the 
first non-white position on the line (2.3). 


Scans for the next match of the last pattern given to / or 
?, but in the reverse direction; this is the reverse of n. 


Opens a new line above the current line and inputs text 
there up to an ESC. A count can be used on dumb termi- 
nals to specify a number of lines to be opened; this is gen- 
erally obsolete, as the s/owopen option works better (3.1). 


Puts the last deleted text back before/above the cursor. 
The text goes back as whole lines above the cursor if it 
was deleted as whole lines. Otherwise the text is inserted 
between the characters before and at the cursor. May be 
preceded by a named buffer specification "x to retrieve 
the contents of the buffer; buffers 1-9 contain deleted 
material, buffers a—z are available for general use (4.3). 


Quits from vi to ex command mode. In this mode, whole 
lines form commands, ending with a RETURN. You can 
give all the : commands; the editor supplies the : as a 
prompt (8.7). 


Replaces characters on the screen with characters you type 
(overlay fashion). Terminates with an ESC. 


Changes whole lines, a synonym for cc. A count substi- 
tutes for that many lines. The lines are saved in the 
numeric buffers, and erased on the screen before the sub- 
stitution begins. 


Takes a single following character, locates the character 
before the cursor in the current line, and places the cursor 
just after that character. A count repeats the effect. 
Most useful with operators such as d (4.1). 


Restores the current line to its state before you started 
changing it (3.5). 
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< 


ZZ 


{[ 


I 


Unused. 


Moves forward to the beginning of a word in the current 
line, where words are defined as sequences of blank/non- 
blank characters. A count repeats the effect (2.4). 


Deletes the character before the cursor. A count repeats 
the effect, but only characters on the current line are 
deleted. 


Yanks a copy of the current line into the unnamed buffer, 
to be put back by a later p or P; a very useful synonym 
for yy. A count yanks that many lines. May be preceded 
by a buffer name to put lines in that buffer (4.3). 


Exits the editor. (Same as :xCR.) If any changes have 
been made, the buffer is written out to the current file. 
Then the editor quits. 


Backs up to the previous section boundary. A section 
begins at each macro in the sections option, normally a 
‘.NH’ or ‘.SH’ and also at lines which which start with a 
formfeed ~L. Lines beginning with { also stop [[; this 
makes it useful for looking backwards, a function at a 
time, in C programs. If the option lisp is set, stops at 
each ( at the beginning of a line, and is thus useful for 
moving backwards at the top level LISP objects. (4.2, 6.1, 
6.6, 8.2). 


Unused. 


Forward to a section boundary, see [[ for a definition 
(4.2, 6.1, 6.6, 8.2). 


Moves to the first non-white position on the current line 
(4.4). 


Unused. 


When followed by a ~ returns to the previous context. 
The previous context is set whenever the current line is 
moved in a non-relative way. When followed by a letter 
a-z, returns to the position which was marked with this 
letter with a m command. When used with an operator 
such as d, the operation takes place from the exact 
marked place to the current position within the line; if 
you use ~, the operation takes place over complete lines 
(2.2, 5.3). 
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Appends arbitrary text after the current cursor position, 
the insert can continue onto multiple lines by using 
RETURN within the insert. A count causes the inserted 
text to be replicated, but only if the inserted text is all on 
one line. The insertion terminates with an ESC (3.1, 8.2). 


Backs up to the beginning of a word in the current line. 
A word is a sequence of alphanumerics, or a sequence of 
special characters. A count repeats the effect (2.4). 


An operator which changes the following object, replacing 
it with the following input text up to an ESC. If more 
than part of a single line is affected, the text which is 
changed away is saved in the numeric named buffers. If 
only part of the current line is affected, then the last char- 
acter to be changed away is marked with a $. A count 
causes that many objects to be affected, thus both 3c) and 
c3) change the following three sentences (8.4). 


An operator which deletes the following object. If more 
than part of a line is affected, the text is saved in the 
numeric buffers. A count causes that many objects to be 
affected; thus 3dw is the same as d3w (3.3, 3.4, 4.1, 8.4). 


Advances to the end of the next word, defined as for b 
and w. A count repeats the effect (2.4, 3.1). 


Finds the first instance of the next character following the 
cursor on the current line. A count repeats the find 
(4.1). 

Unused. 


Left arrow. Moves the cursor one character to the left. 
Like the other arrow keys, either h, the left arrow key, 
or one of the synonyms (~H) has the same effect. On v2 
editors, arrow keys on certain kinds of terminals (those 
which send escape sequences, such as vt52, cl00, or hp) 
cannot be used. A count repeats the effect (3.1, 8.5). 


Inserts text before the cursor, otherwise like a (8.2). 


Down arrow. Moves the cursor one line down in the 
same column. If the position does not exist, vi comes as 
close as possible to the same column. Synonyms include 
*J (linefeed) and “N. 


Up arrow. Moves the cursor one line up. “P is a 
synonym. 
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] Right arrow. Moves the cursor one character to the 
right. SPACE is a synonym. 


m Marks the current position of the cursor in the mark 
register which is specified by the next character a-z. 
Return to this position or use with an operator using ~ or 


- (8.3). 

n Repeats the last / or ? scanning commands (2.2). 

0 Opens new lines below the current line; otherwise like O 
(3.1). 


Puts text after/below the cursor; otherwise like P (6.3). 
q Unused. 


Replaces the single character at the cursor with a single 
character you type. The new character may be a 
RETURN; this is the easiest way to split lines. A count 
replaces each of the following count characters with the 
single character given; see R above which is the more usu- 
ally useful iteration of r (3.2). 


s Changes the single character under the cursor to the text 
which follows up to an ESC; given a count, that many 
characters from the current line are changed. The last 
character to be changed is marked with $ as in ¢ (3.2). 


t Advances the cursor upto the character before the next 
character typed. Most useful with operators such as d and 
c to delete the characters up to a following character. 
You can use . to delete more if this doesn’t delete enough 
the first time (4.1). 


u Undoes the last change made to the current buffer. If 
repeated, will alternate between these two states, thus is 
its own inverse. When used after an insert which inserted 
text on more than one line, the lines are saved in the 
numeric named buffers (3.5). 


v Unused. 

w Advances to the beginning of the next word, as defined 
by b (2.4). 

x Deletes the single character under the cursor. With a 


count deletes deletes that many characters forward from 
the cursor position, but only on the current line (6.5). 
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“2L) 


An operator, yanks the following object into the unnamed 
temporary buffer. If preceded by a named buffer specifi- 
cation, "x, the text is placed in that buffer also. Text can 
be recovered by a later p or P (8.4). 


Redraws the screen with the current line placed as speci- 
fied by the following character: RETURN specifies the top 
of the screen, . the center of the screen, and — at the bot- 
tom of the screen. A count may be given after the z and 
before the following character to specify the new screen 
size for the redraw. A count before the z gives the 
number of the line to place in the center of the screen 
instead of the default current line. (5.4) 


Retreats to the beginning of the beginning of the preced- 
ing paragraph. A paragraph begins at each macro in the 
paragraphs option, normally ‘.IP’, ‘.LP’, ‘.PP’, ‘.QP’ and 
‘bp’. A paragraph also begins after a completely empty 
line, and at each section boundary (see [[ above) (4.2, 
6.8, 8.6). 


Places the cursor on the character in the column specified 
by the count (8.1, 8.2). 


Advances to the beginning of the next paragraph. See { 
for the definition of paragraph (4.2, 6.8, 8.6). 


Unused. 


Interrupts the editor, returning it to command accepting 
state (1.6, 8.5) 
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Vi Command & Function Reference 


1. Author’s Disclaimer 


This document does not claim to be 100% complete. There are a few 
commands listed in the original document that I was unable to test 
either because I do not speak lisp, because they required programs we 
don’t have, or because I wasn’t able to make them work. In these 
cases J left the command out. The commands listed in this document 
have been tried and are known to work. It is expected that prospec- 
tive users of this document will read it once to get the flavor of every- 
thing that vi can do and then use it as a reference document. Experi- 
mentation is recommended. If you don’t understand a command, try 
it and see what happens. 


NOTE 


In revising this document, I have attempted to make it com- 
pletely reflect version 2.12 of vi. It does not attempt to docu- 
ment the VAX version (version 3), but with one or two excep- 
tions (wrapmargin, arrow keys) everything said about 2.12 
should apply to 3.1. Mark Horton 


Source: Alan P.W. Hewett ( Revised for version 2.12 by Mark Horton), Vi Com- 
mand & Function Reference (Berkeley, CA: University of California). 
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2. Notation 


[option] is used to denote optional parts of a command. Many vi 
commands have an optional count. [#] means that an optional 
number may precede the command to multiply or iterate the com- 
mand. {variable item} is used to denote parts of the command 
which must appear, but can take a number of different values. 
<character [-character]> means that the character or one of the char- 
acters in the range described between the two angle brackets is to be 
typed. For example <esc> means the escape key is to be typed. <a- 
z> means that a lower case letter is to be typed. ~<character> 
means that the character is to be typed as a control character, that is, 
with the <#I> key held down while simultaneously typing the speci- 
fied character. In this document control characters will be denoted 
using the upper case character, but ~<uppercase chr> and ~<lower- 
case chr> are equivalent. That is, for example, <~D> is equal to 
<*d>. The most common character abbreviations used in this list are 
as follows: 


<esc> escape, octal 033 
<cr> carriage return, ~M, octal 015 
<lf> linefeed ~J, octal 012 
<nl> newline, ~J, octal 012 (same as linefeed) 
<bs> backspace, ~H, octal 010 
<tab> tab, “I, octal 011 
<bell> bell, ~G, octal 07 
<ff> formfeed, ~L, octal 014 
<sp> space, octal 040 
<del> delete, octal 0177 
3. Basics 


To run vi the shell variable TERM must be defined and exported to 
your environment. How you do this depends on which shell you are 
using. You can tell which shell you have by the character it prompts 
you for commands with. The Bourne shell prompts with ‘$’, and the 
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C shell prompts with ‘%’. For these examples, we will suppose that 
you are using an HP 2621 terminal, whose termcap name is “2621”. 


3.1 Bourne Shell 


To manually set your terminal type to 2621 you would type: 


TERM=2621 
export TERM 


There are various ways of having this automatically or semi- 
automatically done when you log in. Suppose you usually dial in on a 
2621. You want to tell this to the machine, but still have it work 
when you use a hardwired terminal. The recommended way, if you 
have the tset program, is to use the sequence 


tset —s —d 2621 > tset$$ 
. tset$$ 
rm tset$$ 


in your .login (for csh) or the same thing using ‘.’ instead of ‘source’ 
in your .profile (for sh). The above line says that if you are dialing 
in you are on a 2621, but if you are on a hardwired terminal it fig- 
ures out your terminal type from an on-line list. 


3.2 The C Shell 


To manually set your terminal type to 2621 you would type: 
setenv TERM 2621 


There are various ways of having this automatically or semi- 
automatically done when you log in. Suppose you usually dial in on a 
2621. You want to tell this to the machine, but still have it work 
when you use a hardwired terminal. The recommended way, if you 
have the tset program, is to use the sequence 


tset —s —d 2621 > tset$$ 
source tset$$ 
rm tset$$ 


in your .login.* The above line says that if you are dialing in you are 
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on a 2621, but if you are on a hardwired terminal it figures out your 
terminal type from an on-line list. 


4. Normal Commands 


Vi is a visual editor with a window on the file. What you see on the 
screen is vi’s current notion of what your file will contain, (at this 
point in the file), when it is written out. Most commands do not 
cause any change in the screen until the complete command is typed. 
Should you get confused while typing a command, you can abort the 
command by typing an <del> character. You will know you are back 
to command level when you hear a <bell>. Usually typing an <esc> 
will produce the same result. When vi gets an improperly formatted 
command it rings the <bell>. Following are the vi commands broken 
down by function. 


4.1 Entry and Exit 


To enter vi on a particular file, type 
vi file 


The file will be read in and the cursor will be placed at the beginning 
of the first line. The first screenfull of the file will be displayed on 
the terminal. 


To get out of the editor, type 
ZZ 


If you are in some special mode, such as input mode or the middle of 
a multi-keystroke command, it may be necessary to type <esc> first. 


* On a version 6 system without environments, the invocation of tset is simpler, 


just add the line ‘“‘tset -d 2621”’ to your .login or .profile. 
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4.2 Cursor and Page Motion 


NOTE SSS 


The arrow keys (see the next four commands) on certain kinds 
of terminals will not work with the PDP-11 version of vi. The 
control versions or the hjkl versions will work on any terminal. 
Experienced users prefer the hjkl keys because they are always 
right under their fingers. Beginners often prefer the arrow 
keys, since they do not require memorization of which hjkl key 
is which. The mnemonic value of hjkl is clear from looking at 
the keyboard of an adm3a. 


[#]<bs> or 
[#]h or [#]- 


[#]“N or [#]j 
or [#]} or 
[#]<If> 


(#]~P or [#]k 


Move the cursor to the left one character. Cursor 
stops at the left margin of the page. If # is given, 
these commands move that many spaces. 


Move down one line. Moving off the screen scrolls 
the window to force a new line onto the screen. 
Mnemonic: Next 


Move up one line. Moving off the top of the screen 
forces new text onto the screen. Mnemonic: Previ- 
ous 


Move to the right one character. Cursor will not go 
beyond the end of the line. 


Move the cursor up the screen to the beginning of 
the next line. Scroll if necessary. 


Move the cursor down the screen to the beginning 
of the next line. Scroll up if necessary. 


Move the cursor to the end of the line. If there is a 
count, move to the end of the line ‘‘#”’ lines for- 
ward in the file. 


Move the cursor to the beginning of the first word 
on the line. 


Move the cursor to the left margin of the current 
line. 


Move the cursor to the column specified by the 
count. The default is column zero. 
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[#]w Move the cursor to the beginning of the next word. 
If there is a count, then move forward that many 
words and position the cursor at the beginning of 
the word. Mnemonic: next-word 


[#]W Move the cursor to the beginning of the next word 
which follows a “white space’? (<sp>, <tab>, or 
<nl>). Ignore other punctuation. 


[#]b Move the cursor to the preceding word. Mnemonic: 
backup-word 


[#]B Move the cursor to the preceding word that is 
separated from the current word by a ‘“‘white space”’ 
(<sp>, <tab>, or <nl>). 


[#]e Move the cursor to the end of the current word or 
the end of the “#’’th word hence. Mnemonic: end- 
of-word 

[#]E Move the cursor to the end of the current word 
which is delimited by “‘white space” (<sp>, <tab>, 
or <nl>). 

{line Move the cursor to the line specified. Of particular 

number]G use are the sequences “1G” and ‘“‘G’’, which move 


the cursor to the beginning and the end of the file 
respectively. Mnemonic: Go-to 


NOTE 


The next four commands (~D, ~U, ~F, ~B) are not true 
motion commands, in that they cannot be used as the object of 
commands such as delete or change. 


[#]~D Move the cursor down in the file by ‘“#” lines (or 
the last “#’’ if a new count isn’t given. The initial 
default is half a page.) The screen is simultaneously 
scrolled up. Mnemonic: Down 


[#]~U Move the cursor up in the file by ‘‘#” lines. The 
screen is simultaneously scrolled down. Mnemonic: 
Up 

[#]°F Move the cursor to the next page. A count moves 


that many pages. Two lines of the previous page 
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% 


are kept on the screen for continuity if possible. 
Mnemonic: Forward-a-page 


Move the cursor to the previous page. Two lines of 
the current page are kept if possible. Mnemonic: 
Backup-a-page 


Move the cursor to the beginning of the next sen- 
tence. A sentence is defined as ending with a ‘‘.”’, 
“or ‘‘?” followed by two spaces or a <nl>. 


Move the cursor backwards to the beginning of a 
sentence. 


Move the cursor to the beginning of the next para- 
graph. This command works best inside nroff docu- 
ments. It understands two sets of nroff macros, 
-ms and -—mm, for which the commands “.IP”’, 
“LP”, “PP”, ““.QP”, “.P”, as well as the nroff 
command ‘‘.bp” are considered to be paragraph del- 
imiters. A blank line also delimits a paragraph. 
The nroff macros that it accepts as paragraph delim- 
iters is adjustable. See paragraphs under the Set 
Commands section. 


Move the cursor backwards to the beginning of a 
paragraph. 


Move the cursor to the next ‘“‘section’’, where a sec- 
tion is defined by two sets of nroff macros, —ms and 
-mm, in which “.NH”, ‘*.SH”’, and ‘‘.H”’ delimit a 
section. A line beginning with a <ff><nl> 
sequence, or a line beginning with a ‘{”’ are also 
considered to be section delimiters. The last option 
makes it useful for finding the beginnings of C func- 
tions. The nroff macros that are used for section 
delimiters can be adjusted. See sections under the 
Set Commands section. 


Move the cursor backwards to the beginning of a 
section. 


Move the cursor to the matching parenthesis or 
brace. This is very useful in C or lisp code. If the 
cursor is sitting on a () { or } the cursor is moved 
to the matching character at the other end of the 
section. If the cursor is not sitting on a brace or a 
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m<a-z> 


parenthesis, vi searches forward until it finds one 
and then jumps to the match mate. 


If there is no count move the cursor to the top left 
position on the screen. If there is a count, then 
move the cursor to the beginning of the line ‘“#” 
lines from the top of the screen. Mnemonic: Home 


If there is no count move the cursor to the begin- 
ning of the last line on the screen. If there is a 
count, then move the cursor to the beginning of the 
line ‘‘#’’ lines from the bottom of the screen. 
Mnemonic: Last 


Move the cursor to the beginning of the middle line 
on the screen. Mnemonic: Middle 


This command does not move the cursor, but it 
marks the place in the file and the character ‘‘<a- 
z>’’ becomes the label for referring to this location 
in the file. See the next two commands. 
Mnemonic: mark 


NOTE 


The mark command is not a motion, and 
cannot be used as the target of commands 
such as delete. 


Move the cursor to the beginning of the line that is 
marked with the label “‘<a-z>’’. 


Move the cursor to the exact position on the line 
that was marked with with the label ‘‘<a-z>”’. 


Move the cursor back to the beginning of the line 
where it was before the last “‘non-relative’’ move. 
A “non-relative’” move is something such as a 
search or a jump to a specific line in the file, rather 
than moving the cursor or scrolling the screen. 


Move the cursor back to the exact spot on the line 
where it was located before the last ‘‘non-relative”’ 
move. 
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4.3 Searches 


The following commands allow you to search for items in a file. 


[#]f{chr} 


[#]F {chr} 


[#]t {chr} 


Search forward on the line for the next or “‘#’’th 
occurrence of the character “‘chr’’. The cursor is placed 
at the character of interest. Mnemonic: find character 


Search backwards on the line for the next or ‘“‘#’’th 
occurrence of the character ‘“‘chr’’. The cursor is placed 
at the character of interest. 


Search forward on the line for the next or “#’’th 
occurrence of the character ‘“‘chr’’. The cursor is placed 
just preceding the character of interest. Mnemonic: 
move cursor up to character 


[#]T{chr} Search backwards on the line for the next or ‘‘#’’th 


[#]; 


occurrence of the character ‘“‘chr’. The cursor is placed 
just preceding the character of interest. 


Repeat the last ‘‘f”, “F’, “t” or ““T’’ command. 


{#], Repeat the last ‘“‘f’, ““F’’, ‘“‘t” or ‘““T’? command, but in 
the opposite search direction. This is useful if you 
overshoot. 

[#]/[string]/<nl> 


Search forward for the next occurrence of ‘“‘string’’. 
Wrap around at the end of the file does occur. The 
final </> is not required. 


[#] ?[string]?<nl> 


N 


Search backwards for the next occurrence of ‘‘string’’. 
If a count is specified, the count becomes the new win- 
dow size. Wrap around at the beginning of the file 
does occur. The final <?> is not required. 


Repeat the last /[string]/ or [string]? search. 
Mnemonic: next occurrence. 


Repeat the last /[string]/ or ?[string]? search, but in the 
reverse direction. 


:g/[string]/[editor command] <nl> 


Using the : syntax it is possible to do global searches ala 
the standard UNIX ‘‘ed”’ editor. 
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4.4 Text Insertion 


The following commands allow for the insertion of text. All mul- 
ticharacter text insertions are terminated with an <esc> character. 
The last change can always be undone by typing au. The text insert 
in insertion mode can contain newlines. 


a{text}<esc> Insert text immediately following the cursor posi- 
tion. Mnemonic: append 


Aftext}<esc> Insert text at the end of the current line. 
Mnemonic: Append 


i{text}<esc> Insert text immediately preceding the cursor posi- 
tion. Mnemonic: insert 


I{text}<esc> Insert text at the beginning of the current line. 


o{text}<esc> Insert a new line after the line on which the cursor 
appears and insert text there. Mnemonic: open 
new line 


Otext}<esc> Insert a new line preceding the line on which the 
cursor appears and insert text there. 


4.5 Text Deletion 


The following commands allow the user to delete text in various 
ways. All changes can always be undone by typing the u command. 


[#]x Delete the character or characters starting at the 
cursor position. 


[#]X Delete the character or characters starting at the 
character preceding the cursor position. 


D Deletes the remainder of the line starting at the cur- 
sor. Mnemonic: Delete the rest of line 


[#]d{motion} Deletes one or more occurrences of the specified 
motion. Any motion from sections 4.1 and 4.2 can 
be used here. The d can be stuttered (e.g. [#]dd) 
to delete # lines. 
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4.6 Text Replacement 


The following commands allow the user to simultaneously delete and 
insert new text. All such actions can be undone by typing u following 
the command. 


r<chr> Replaces the character at the current cursor posi- 
tion with <chr>. This is a one character replace- 
ment. No <esc> is required for termination. 
Mnemonic: replace character 


R{text}<esc> Starts overlaying the characters on the screen with 
whatever you type. It does not stop until an <esc> 
is typed. 

[#]s{text}<esc> Substitute for ‘‘#’ characters beginning at the 
current cursor position. A “‘$’’ will appear at the 
position in the text where the “‘#’th character 
appears so you will know how much you are eras- 
ing. Mnemonic: substitute 


[#]S{text} <esc> 


Substitute for the entire current line (or lines). If 
no count is given, a ‘“‘$” appears at the end of the 
current line. If a count of more than 1 is given, all 
the lines to be replaced are deleted before the 
insertion begins. 


[#]c{motion} {text} <esc> 


Change the specified ‘“‘motion”’ by replacing it with 
the insertion text. A “‘$’’ will appear at the end of 
the last item that is being deleted unless the dele- 
tion involves whole lines. Motion’s can be any 
motion from sections 4.1 or 4.2. Stuttering the c 
(e.g. [#}]cc) changes # lines. 


4.7 Moving Text 


Vi provides a number of ways of moving chunks of text around. 
There are nine buffers into which each piece of text which is deleted 
or “yanked” is put in addition to the ‘‘undo” buffer. The most 
recent deletion or yank is in the ‘‘undo” buffer and also usually in 
buffer 1, the next most recent in buffer 2, and so forth. Each new 
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deletion pushes down all the older deletions. Deletions older than 9 
disappear. There is also a set of named registers, a-z, into which text 
can optionally be placed. If any delete or replacement type command 
is preceded by "<a-z>, that named buffer will contain the text 
deleted after the command is executed. For example, "a3dd will 
delete three lines starting at the current line and put them in buffer 
"a.* There are two more basic commands and some variations useful 
in getting and putting text into a file. 


['" <a-z>][#]y{motion} 


["<a-z>][#]¥ 


["<a-z>]p 


* 


Yank the specified item or “#’’ items and put in 
the “undo” buffer or the specified buffer. ‘The 
variety of “‘items’” that can be yanked is the same 
as those that can be deleted with the ‘‘d’’ command 
or changed with the ‘“‘c’’ command. In the same 
way that “dd” means delete the current line and 
“ec”? means replace the current line, ‘“‘yy’? means 
yank the current line. 


Yank the current line or the ‘“#’’ lines starting 
from the current line. If no buffer is specified, 
they will go into the “undo”’ buffer, like any delete 


would. It is equivalent to ‘yy’. Mnemonic: 
Yank 


Put “undo” buffer or the specified buffer down 
after the cursor. If whole lines were yanked or 
deleted into the buffer, then they will be put down 
on the line following the line the cursor is on. If 
something else was deleted, like a word or sen- 
tence, then it will be inserted immediately follow- 
ing the cursor. Mnemonic: put buffer 


It should be noted that text in the named buffers 
remains there when you start editing a new file 
with the :e file<esc> command. Since this is so, it 
is possible to copy or delete text from one file and 
carry it over to another file in the buffers. How- 
ever, the undo buffer and the ability to undo are 


Referring to an upper case letter as a buffer name (A-Z) is the same as 


referring to the lower case letter, except that text placed in such a buffer is 
appended to it instead of replacing it. 
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lost when changing files. 


["<a-z>]P Put “undo” buffer or the specified buffer down 


before the cursor. If whole lines where yanked or 
deleted into the buffer, then they will be put down 
on the line preceding the line the cursor is on. If 
something else was deleted, like a word or sen- 
tence, then it will be inserted immediately preced- 
ing the cursor. 


[#]>{motion} The shift operator will right shift all the text from 


the line on which the cursor is located to the line 
where the motion is located. The text is shifted by 
one shiftwidth. (See section 6.) >> means right 
shift the current line or lines. 


[#]<{motion} The shift operator will left shift all the text from 


the line on which the cursor is located to the line 
where the item is located. The text is shifted by 
one shiftwidth. (See section 6.) << means left 
shift the current line or lines. Once the line has 
reached the left margin it is not further affected. 


[#]={motion} Prettyprints the indicated area according to lisp 


conventions. The area should be a lisp s- 
expression. 


4.8 Miscellaneous Commands 


Vi has a number of miscellaneous commands that are very useful. 
They are: 


ZZ, 


This is the normal way to exit from vi. If any changes have 
been made, the file is written out. Then you are returned 
to the shell. 


Redraw the current screen. This is useful if someone 
“‘write’’s you while you are in ‘‘vi” or if for any reason gar- 
bage gets onto the screen. 


On dumb terminals, those not having the “‘delete line’ func- 
tion (the vti00 is such a terminal), vi saves redrawing the 
screen when you delete a line by just marking the line with 
an “@” at the beginning and blanking the line. If you want 
to actually get rid of the lines marked with ‘‘@” and see 
what the page looks like, typing a ~R will do this. 


Vi Command & Function Reference 5—13 


“Dot” is a particularly useful command. It repeats the last 
text modifying command. Therefore you can type a com- 
mand once and then to another place and repeat it by just 


typing ‘‘.”’. 

u Perhaps the most important command in the editor, u 
undoes the last command that changed the buffer. 
Mnemonic: undo 


U Undo all the text modifying commands performed on the 
current line since the last time you moved onto it. 


[#]J Join the current line and the following line. The <nl> is 
deleted and the two lines joined, usually with a space 
between the end of the first line and the beginning of what 
was the second line. If the first line ended with a ‘‘period’’, 
then two spaces are inserted. A count joins the next # lines. 
Mnemonic: Join lines 


Q Switch to ex editing mode. In this mode vi will behave very 
much like ed. The editor in this mode will operate on single 
lines normally and will not attempt to keep the ‘‘window”’ 
up to date. Once in this mode it is also possible to switch to 
the open mode of editing. By entering the command [line 
numberJopen<nl> you enter this mode. It is similar to the 
normal visual mode except the window is only one line long. 
Mnemonic: Quit visual mode 


-] An abbreviation for a tag command. The cursor should be 
positioned at the beginning of a word. That word is taken 
as a tag name, and the tag with that name is found as if it 
had been typed in a :tag command. 


[#]!{motion} {UNIX cmd} <nl> 


Any UNIX filter (e.g. command that reads the standard 
input and outputs something to the standard output) can be 
sent a section of the current file and have the output of the 
command replace the original text. Useful examples are 
programs like cb, sort, and nroff. For instance, using sort 
it would be possible to sort a section of the current file into 
a new list. Using !! means take a line or lines starting at the 
line the cursor is currently on and pass them to the UNIX 
command. 
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NOTE 


To just escape to the shell for one command, use 
:!{cmd}<nl>, see section 5. 


z{#}<nl> 


This resets the current window size to ‘‘#”’ lines and redraws 
the screen. 


4.9 Special Insert Characters 


There are some characters that have special meanings during insert 
modes. They are: 


“Vv During inserts, typing a ~V allows you to quote control 
characters into the file. Any character typed after the 
~V will be inserted into the file. 


[~]°D or<*D> without any argument backs up one shiftwidth. 

[0]“D This is necessary to remove indentation that was inserted 
by the autoindent feature. ~<*D> temporarily removes 
all the autoindentation, thus placing the cursor at the left 
margin. On the next line, the previous indent level will 
be restored. This is useful for putting ‘‘labels’’ at the left 
margin. 0<~D> says remove all autoindents and stay that 
way. Thus the cursor moves to the left margin and stays 
there on successive lines until <tab>’s are typed. As with 
the <tab>, the <*D> is only effective before any other 
“‘non-autoindent” controlling characters are typed. 
Mnemonic: Delete a shiftwidth 


“Ww If the cursor is sitting on a word, <*W> moves the cur- 
sor back to the beginning of the word, thus erasing the 
word from the insert. Mnemonic: erase Word 


<bs> The backspace always serves as an erase during insert 
modes in addition to your normal ‘‘erase’’ character. To 
insert a <bs> into your file, use the <~ V> to quote it. 
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5. : Commands 


Typing a “‘:’? during command mode causes vi to put the cursor at the 
bottom on the screen in preparation for a command. In the “:” 
mode, vi can be given most ed commands. It is also from this mode 
that you exit from vi or switch to different files. All commands of 
this variety are terminated by a <nl>, <cr>, or <esc>. 


:w[!] [file] Causes vi to write out the current text to the disk. It is 
written to the file you are editing unless “‘file’’ is sup- 
plied. If ‘‘file’’ is supplied, the write is directed to that 
file instead. If that file already exists, vi will not per- 
form the write unless the ‘‘!”’ is supplied indicating you 
really want to destroy the older copy of the file. 


:q[!] Causes vi to exit. If you have modified the file you are 
looking at currently and haven’t written it out, vi will 
refuse to exit unless the ‘‘!’”’ is supplied. 


:e[!] [+[cmd]] [file] 


Start editing a new file called “‘file” or start editing the 
current file over again. The command “‘:e!”’ says 
“ignore the changes I’ve made to this file and start over 
from the beginning’. It is useful if you really mess up 
the file. The optional ‘‘+’’ says instead of starting at 
the beginning, start at the ‘‘end’’, or, if ‘‘cmd”’ is sup- 
plied, execute ‘‘cmd’’ first. Useful cases of this are 
where cmd is ‘“‘n’”’ (any integer) which starts at line 
number n, and ‘‘/text’’, which searches for ‘‘text’? and 
starts at the line where it is found. 


Switch back to the place you were before your last tag 
command. If your last tag command stayed within the 
file, ~~ returns to that tag. If you have no recent tag 
command, it will return to the same place in the previ- 
ous file that it was showing when you switched to the 
current file. 


n{!] Start editing the next file in the argument list. Since vi 
can be called with multiple file names, the ‘‘:n’’ com- 
mand tells it to stop work on the current file and switch 
to the next file. If the current file was modifies, it has 
to be written out before the “‘:n’’ will work or else the 
“PP must be supplied, which says discard the changes I 
made to the current file. 
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:n{!] file [file file ...] 


s!temd 


‘ta[!] tag 


Replace the current argument list with a new list of files 
and start editing the first file in this new list. 


Read in a copy of ‘file’ on the line after the cursor. 


Execute the “‘cmd” and take its output and put it into 
the file after the current line. 


Execute any UNIX shell command. 


Vi looks in the file named tags in the current directory. 
Tags is a file of lines in the format: 


tag filename vi-search-command 


If vi finds the tag you specified in the :ta command, it 
stops editing the current file if necessary and if the 
current file is up to date on the disk and switches to the 
file specified and uses the search pattern specified to 
find the ‘‘tagged”’ item of interest. This is particularly 
useful when editing multi-file C programs such as the 
operating system. There is a program called ctags 
which will generate an appropriate tags file for C and 
f77 programs so that by saying :ta function<nl> you 
will be switched to that function. It could also be use- 
ful when editing multi-file documents, though the tags 
file would have to be generated manually. 


6. Special Arrangements for Startup 


Vi takes the value of $TERM and looks up the characteristics of that 
terminal in the file /etce/termcap. If you don’t know vi’s name for the 
terminal you are working on, look in /etc/termcap. 


When vi starts, it attempts to read the variable EXINIT from your 
environment.* If that exists, it takes the values in it as the default 
values for certain of its internal constants. See the section on ‘‘Set 
Values” for further details. If EXINIT doesn’t exist you will get all 
the normal defaults. 


On version 6 systems: Instead of EXINIT, put the startup commands in the 
file .exre in your home directory. 
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Should you inadvertently hang up the phone while inside vi, or should 
the computer crash, all may not be lost. Upon returning to the sys- 
tem, type: 


vi —r file 


This will normally recover the file. If there is more than one tem- 
porary file for a specific file name, vi recovers the newest one. You 
can get an older version by recovering the file more than once. The 
command “‘vi -r’’ without a file name gives you the list of files that 
were saved in the last system crash (but not the file just saved when 
the phone was hung up). 


7. Set Commands 


Vi has a number of internal variables and switches which can be set to 
achieve special affects. These options come in three forms, those that 
are switches, which toggle from off to on and back, those that require 
a numeric value, and those that require an alphanumeric string value. 
The toggle options are set by a command of the form: 


‘set option<nl> 
and turned off with the command: 
‘set nooption<nl> 
Commands requiring a value are set with a command of the form: 
‘set option=value<nl> 
To display the value of a specific option type: 
‘set option?<nl> 
To display only those that you have changed type: 
set<nl> 


and to display the long table of all the settable parameters and their 
current values type: 


‘set all<nl> 
Most of the options have a long form and an abbreviation. Both are 
listed in the following table as well as the normal default value. 


To arrange to have values other than the default used every time you 
enter vi, place the appropriate set command in EXINIT in your 
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environment, e.g. 


EXINIT=’set ai aw terse sh=/bin/csh’ 
export EXINIT 


or 


setenv EXINIT ’set ai aw terse sh=/bin/csh’ 


for sh and csh, respectively. These are usually placed in your . profile 
or .login. If you are running a system without environments (such as 
version 6) you can place the set command in the file .exre in your 
home directory. 


autoindent 
al 


autoprint 
ap 


autowrite 
aw 


beautify 
bf 


directory 
dir 


errorbells 
eb 


Default: noai Type: toggle 


When in autoindent mode, vi helps you indent code by 
starting each line in the same column as the preceding 
line. Tabbing to the right with <tab> or <“T> will 
move this boundary to the right, and it can be moved 
to the left with <~D>. 

Default: ap Type: toggle 


Causes the current line to be printed after each ex text 
modifying command. This is not of much interest in 
the normal vi visual mode. 


Default: noaw Type: toggle 


Autowrite causes an automatic write to be done if there 
are unsaved changes before certain commands which 
change files or otherwise interact with the outside 
world. These commands are :!, :tag, :next, :rewind, 
-*, and ~]. 

Default: nobf Type: toggle 

Causes all control characters except <tab>, <nl>, and 
<ff> to be discarded. 

Default: dir=/tmp Type: string 

This is the directory in which vi puts its temporary file. 


Default: noeb Type: toggle 


Error messages are preceded by a <bell>. 
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hardtabs 
ht 


ignorecase 
ic 


lisp 


list 


magic 


number 
nu 


open 


optimize 
opt 


paragraphs 
para 


Default: hardtabs=8 Type: numeric 


This option contains the value of hardware tabs in your 
terminal, or of software tabs expanded by the Unix sys- 
tem. 


Default: noic Type: toggle 


All upper case characters are mapped to lower case in 
regular expression matching. 


Default: nolisp Type: roggle 


Autoindent for lisp code. The commands ( ) [[ and ]] 
are modified appropriately to affect s-expressions and 
functions. 


Default: nolist Type: toggle 


All printed lines have the <tab> and <nl> characters 
displayed visually. 
Default: magic Type: toggle 


Enable the metacharacters for matching. These include 
. * < > [string] [~string] and [<chr>-<chr>]. 


Default: nonu Type: toggle 
Each line is displayed with its line number. 
Default: open Type: toggle 


When set, prevents entering open or visual modes from 
ex or edit. Not of interest from vi. 


Default: opt Type: toggle 


Basically of use only when using the ex capabilities. 
This option prevents automatic <cr>s from taking 
place, and speeds up output of indented lines, at the 
expense of losing typeahead on some versions of UNIX. 


Default: para=IPLPPPQPP bp Type: string 


Each pair of characters in the string indicate nroff mac- 
ros which are to be treated as the beginning of a para- 
graph for the € and } commands. The default string is 
for the -ms and -mm macros. To indicate one letter 
nroff macros, such as .P or .H, quote a space in for the 
second character position. For example: 
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prompt 


redraw 


report 


scroll 


sections 


shell 
sh 


shiftwidth 
Sw 


‘set paragraphs=P\ bp<nl> 


would cause vi to consider .P and .bp as paragraph del- 
imiters. 


Default: prompt Type: toggle 


In ex command mode the prompt character : will be 
printed when ex is waiting for a command. This is not 
of interest from vi. 


Default: noredraw Type: toggle 


On dumb terminals, force the screen to always be up to 
date, by sending great amounts of output. Useful only 
at high speeds. 


Default: report=5 Type: numeric 


This sets the threshold for the number of lines modi- 
fied. When more than this number of lines are modi- 
fied, removed, or yanked, vi will report the number of 
lines changed at the bottom of the screen. 


Default: scrolli={1/2 window} Type: numeric 


This is the number of lines that the screen scrolls up or 
down when using the <*U> and <*D> commands. 


Default: sections=SHNHH HU Type: string 


Each two character pair of this string specify nroff 
macro names which are to be treated as the beginning 
of a section by the ]] and [[ commands. The default 
string is for the -ms and -mm macros. To enter one 
letter nroff macros, use a quoted space as the second 
character. See paragraphs for a fuller explanation. 


Default: sh=from environment SHELL or /bin/sh 
Type: string 

This is the name of the sh to be used for “escaped” 
commands. 

Default: sw=8 Type: numeric 


This is the number of spaces that a <~ T> or <7 D> will 
move over for indenting, and the amount < and > shift 
by. 
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showmatch 
sm 


slowopen 
slow 


tabstop 
ts 


taglength 
tl 


term 


terse 


Warn 


window 


Default: nosm Type: toggle 


When a ) or } is typed, show the matching ( or { by 
moving the cursor to it for one second if it is on the 
current screen. 


Default: terminal dependent Type: toggle 


On terminals that are slow and unintelligent, this option 
prevents the updating of the screen some of the time to 
improve speed. 


Default: ts=8 Type: numeric 


<tab>s are expanded to boundaries that are multiples of 
this value. 


Default: tl=0 Type: numeric 


If nonzero, tag names are only significant to this many 
characters. 


Default: (from environment TERM, else dumb) ‘Type: 
string 


This is the terminal and controls the visual displays. It 
cannot be changed when in ‘‘visual’’ mode, you have to 
Q to command mode, type a set term command, and 
do ‘“‘vi.”” to get back into visual. Or exit vi, fix $TERM, 
and reenter. The definitions that drive a particular ter- 
minal type are found in the file /ete/termcap. 


Default: terse Type: toggle 
When set, the error diagnostics are short. 
Default: warn Type: toggle 


The user is warned if she/he tries to escape to the shell 
without writing out the current changes. 


Default: window={8 at 600 baud or less, at 1200 baud, 
and screen size — 1 at 2400 baud or more} Type: 
numeric 


This is the number of lines in the window whenever vi 
must redraw an entire screen. It is useful to make this 
size smaller if you are on a slow line. 
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w300 
w1200 
w9600 


wrapscan 
ws 


wrapmargin 
wm 


writeany 
wa 


These set window, but only within the corresponding 
speed ranges. They are useful in an EXINIT to fine 
tune window sizes. For example, 


set w300=4 w1200=12 


causes a 4 lines window at speed up to 600 baud, a 12 
line window at 1200 baud, and a full screen (the 
default) at over 1200 baud. 


Default: ws Type: toggle 


Searches will wrap around the end of the file when is 
option is set. When it is off, the search will terminate 
when it reaches the end or the beginning of the file. 


Default: wm=0 Type: numeric 


Vi will automatically insert a <nl> when it finds a 
natural break point (usually a <sp> between words) 
that occurs within “‘wm”’ spaces of the right margin. 
Therefore with ‘““wm=0” the option is off. Setting it to 
10 would mean that any time you are within 10 spaces 
of the right margin vi would be looking for a <sp> or 
<tab> which it could replace with a <nl>. This is con- 
venient for people who forget to look at the screen 
while they type. (In version 3, wrapmargin behaves 
more like nroff, in that the boundary specified by the 
distance from the right edge of the screen is taken as 
the rightmost edge of the area where a break is 
allowed, instead of the leftmost edge.) 


Default: nowa Type: toggle 


Vi normally makes a number of checks before it writes 
out a file. This prevents the user from inadvertently 
destroying a file. When the ‘“‘writeany’ option is 
enabled, vi no longer makes these checks. 
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6 


SED — A Non-interactive Text Editor 


Abstract 


Sed is a non-interactive context editor that runs on the unix operating 
system. Sed is designed to be especially useful in three cases: 


1. To edit files too large for comfortable interactive editing; 


2. To edit any size file when the sequence of editing commands is 
too complicated to be comfortably typed in interactive mode. 


3. To perform multiple ‘global’ editing functions efficiently in one 
pass through the input. 


This memorandum constitutes a manual for users of sed. 


Introduction 


Sed is a non-interactive context editor designed to be especially useful 
in three cases: 


1. To edit files too large for comfortable interactive editing; 


2. To edit any size file when the sequence of editing commands is 
too complicated to be comfortably typed in interactive mode; 


3. To perform multiple “global’’ editing functions efficiently in 
one pass through the input. 


Since only a few lines of the input reside in core at one time, and no 
temporary files are used, the effective size of file that can be edited is 


Source: Lee E. McMahon, SED — A Non-interactive Text Editor (Murray Hill, 
N.J.: Bell Laboratories, 1978). 
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limited only by the requirement that the input and output fit simul- 
taneously into available secondary storage. 


Complicated editing scripts can be created separately and given to sed 
as a command file. For complex edits, this saves considerable typing, 
and its attendant errors. Sed running from a command file is much 
more efficient than any interactive editor known to the author, even 
if that editor can be driven by a pre-written script. 


The principal loss of functions compared to an interactive editor are 
lack of relative addressing (because of the line-at-a-time operation), 
and lack of immediate verification that a command has done what 
was intended. 


Sed is a lineal descendant of the UNIX editor, ed. Because of the 
differences between interactive and non-interactive operation, consid- 
erable changes have been made between ed and sed; even confirmed 
users of ed will frequently be surprised (and probably chagrined), if 
they rashly use sed without reading Sections 2 and 3 of this docu- 
ment. The most striking family resemblance between the two editors 
is in the class of patterns (‘‘regular expressions’’) they recognize; the 
code for matching patterns is copied almost verbatim from the code 
for ed, and the description of regular expressions in Section 2 is 
copied almost verbatim from the UNIX Programmer’s Manual[1]. 
(Both code and description were written by Dennis M. Ritchie.) 


1. Overall Operation 


Sed by default copies the standard input to the standard output, 
perhaps performing one or more editing commands on each line 
before writing it to the output. This behavior may be modified by 
flags on the command line; see Section 1.1 below. 


The general format of an editing command is: 
[address] ,address2][function][arguments] 


One or both addresses may be omitted; the format of addresses is 
given in Section 2. Any number of blanks or tabs may separate the 
addresses from the function. The function must be present; the avail- 
able commands are discussed in Section 3. The arguments may be 
required or optional, according to which function is given; again, they 
are discussed in Section 3 under each individual function. 
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Tab characters and spaces at the beginning of lines are ignored. 


1.1 Command-line Flags 


Three flags are recognized on the command line: 


-n tells sed not to copy all lines, but only those specified by p 
functions or p flags after s functions (see Section 3.3); 


-e tells sed to take the next argument as an editing command; 


-f tells sed to take the next argument as a file name; the file 
should contain editing commands, one to a line. 


1.2 Order of Application of Editing Commands 


Before any editing is done (in fact, before any input file is even 
opened), all the editing commands are compiled into a form which 
will be moderately efficient during the execution phase (when the 
commands are actually applied to lines of the input file). The com- 
mands are compiled in the order in which they are encountered; this 
is generally the order in which they will be attempted at execution 
time. The commands are applied one at a time; the input to each 
command is the output of all preceding commands. 


The default linear order of application of editing commands can be 
changed by the flow-of-control commands, t and b (see Section 3). 
Even when the order of application is changed by these commands, it 
is still true that the input line to any command is the output of any 
previously applied command. 


1.3 Pattern-space 


The range of pattern matches is called the pattern space. Ordinarily, 
the pattern space is one line of the input text, but more than one line 
can be read into the pattern space by using the N command (Section 
3.6.). 
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1.4 Examples 


Examples are scattered throughout the text. Except where otherwise 
noted, the examples all assume the following input text: 


In Xanadu did Kubla Khan 

A stately pleasure dome decree: 
Where Alph, the sacred river, ran 
Through caverns measureless to man 
Down to a sunless sea. 


(In no case is the output of the sed commands to be considered an 
improvement on Coleridge.) 


Example: 
The command 
2q 
will quit after copying the first two lines of the input. The output will 
be: 


In Xanadu did Kubla Khan 
A stately pleasure dome decree: 


2. Addresses: Selecting Lines for Editing 


Lines in the input file(s) to which editing commands are to be applied 
can be selected by addresses. Addresses may be either line numbers 
or context addresses. 


The application of a group of commands can be controlled by one 
address (or address-pair) by grouping the commands with curly braces 
(‘{ }’)(Sec. 3.6.). 
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2.1 Line-number Addresses 


A line number is a decimal integer. As each line is read from the 
input, a line-number counter is incremented; a line-number address 
matches (selects) the input line which causes the internal counter to 
equal the address line-number. The counter runs cumulatively 
through multiple input files; it is not reset when a new input file is 
opened. 


As a special case, the character $ matches the last line of the last 
input file. 


2.2 Context Addresses 


A context address is a pattern (‘regular expression’) enclosed in 
slashes (‘/’). The regular expressions recognized by sed are con- 
structed as follows: 


1. An ordinary character (not one of those discussed below) is a 
regular expression, and matches that character. 


on 


2. A circumflex at the beginning of a regular expression 
matches the null character at the beginning of a line. 


3. A dollar-sign ‘$’ at the end of a regular expression matches the 
null character at the end of a line. 


4. The characters ‘\n’ match an imbedded newline character, but 
not the newline at the end of the pattern space. 


5. A period ‘.” matches any character except the terminal newline 
of the pattern space. 


6. A regular expression followed by an asterisk ‘*’ matches any 
number (including 0) of adjacent occurrences of the regular 
expression it follows. 


7. A string of characters in square brackets ‘[ ]’ matches any char- 
acter in the string, and no others. If, however, the first charac- 
ter of the string is circumflex ‘~’, the regular expression 
matches any character excepr the characters in the string and the 
terminal newline of the pattern space. 


8. A concatenation of regular expressions is a regular expression 
which matches the concatenation of strings matched by the com- 
ponents of the regular expression. 
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9. A regular expression between the sequences ‘\(’ and ‘\)’ is 
identical in effect to the unadorned regular expression, but has 
side-effects which are described under the s command below 
and specification 10) immediately below. 


10. The expression ‘\d’ means the same string of characters 
matched by an expression enclosed in ‘\(’ and ‘\)’ earlier in the 
same pattern. Here d is a single digit; the string specified is 
that beginning with the dth occurrence of ‘\(’ counting from the 
left. For example, the expression “‘~\(.*\)\1” matches a line 
beginning with two repeated occurrences of the same string. 


11. The null regular expression standing alone (e.g., ‘//’) is 
equivalent to the last regular expression compiled. 


NOTE 


To use one of the special characters (~ $ . * [] \ /) as a literal 
(to match an occurrence of itself in the input), precede the 


special character by a backslash ‘\’. 


For a context address to “‘match” the input requires that the whole 
pattern within the address match some portion of the pattern space. 


2.3 Number of Addresses 


The commands in the next section can have 0, 1, or 2 addresses. 
Under each command the maximum number of allowed addresses is 
given. For a command to have more addresses than the maximum 
allowed is considered an error. 


If a command has no addresses, it is applied to every line in the 
input. 


If a command has one address, it is applied to all lines which match 
that address. 


If a command has two addresses, it is applied to the first line which 
matches the first address, and to all subsequent lines until (and 
including) the first subsequent line which matches the second address. 
Then an attempt is made on subsequent lines to again match the first 
address, and the process is repeated. 


6—6 Programmer's Guide: CTIX Supplement 


Two addres 
Examples: 


/an/ 
/an.*an/ 
/~an/ 
Ld 

IN./ 
/r*an/ 
/\(an\) 


ses are separated by a comma. 


matches lines 1, 3, 4 in our sample text 

matches line 1 

matches no lines 

matches all lines 

matches line 5 

matches lines 1,3, 4 (number = zero!) 
\1/ matches line 1 


3. Functions 


All functions are named by a single character. In the following sum- 
mary, the maximum number of allowable addresses is given enclosed 
in parentheses, then the single character function name, possible argu- 
ments enclosed in angles (< >), an expanded English translation of 
the single-character name, and finally a description of what each 
function does. The angles around the arguments are nor part of the 
argument, and should not be typed in actual editing commands. 


3.1 Who 


(2)d 


(2)n 


le-line Oriented Functions 


delete lines 


The d function deletes from the file (does not write to the 
output) all those lines matched by its address(es). 


It also has the side effect that no further commands are 
attempted on the corpse of a deleted line; as soon as the d 
function is executed, a new line is read from the input, 
and the list of editing commands is re-started from the 
beginning on the new line. 


next line 


The n function reads the next line from the input, replac- 
ing the current line. The current line is written to the 
output if it should be. The list of editing commands is 
continued following the n command. 
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(1)a\ append lines 


<text> F ‘ 
iat The a function causes the argument <text> to be written 


to the output after the line matched by its address. The a 
command is inherently multi-line; @ must appear at the 
end of a line, and <text> may contain any number of 
lines. To preserve the one-command-to-a-line fiction, the 
interior newlines must be hidden by a backslash character 
(‘\’) immediately preceding the newline. The <text> 
argument is terminated by the first unhidden newline (the 
first one not immediately preceded by backslash). 


Once an a function is successfully executed, <text> will be 
written to the output regardless of what later commands 
do to the line which triggered it. The triggering line may 
be deleted entirely; <text> will still be written to the out- 
put. 


The <text> is not scanned for address matches, and no 
editing commands are attempted on it. It does not cause 
any change in the line-number counter. 


(1)i\ insert lines 


<text> . : 3 ° : 
me The i function behaves identically to the a function, 


except that <text> is written to the output before the 
matched line. All other comments about the a function 
apply to the i function as well. 


(2)c\ change lines 


<text> : F ; 
The c function deletes the lines selected by its address(es), 


and replaces them with the lines in <text>. Like a and i, 
c must be followed by a newline hidden by a backslash; 
and interior new lines in <text> must be hidden by 
backslashes. 


The c command may have two addresses, and therefore 
select a range of lines. If it does, all the lines in the range 
are deleted, but only one copy of <text> is written to the 
output, not one copy per line deleted. As with a and i, 
<text> is not scanned for address matches, and no editing 
commands are attempted on it. It does not change the 
line-number counter. 


After a line has been deleted by a c function, no further 
commands are attempted on the corpse. 
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If text is appended after a line by a or r functions, and 
the line is subsequently changed, the text inserted by the c 
function will be placed before the text of the a or r func- 
tions. (The r function is described in Section 3.4.) 


NOTE 


Within the text put in the output by these functions, leading 
blanks and tabs will disappear, as always in sed commands. 
To get leading blanks and tabs into the output, precede the 
first desired blank or tab by a backslash; the backslash will not 
appear in the output. 


Example: 
The list of editing commands: 


n 

a\ 
XXXX 
d 


applied to our standard input, produces: 


In Xanadu did Kubhla Khan 
XXXX 

Where Alph, the sacred river, ran 
XXXX 

Down to a sunless sea. 


In this particular case, the same effect would be produced by either of 
the two following command lists: 


n n 
i\ c\ 
XXXX XXXX 
d 
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3.2 Substitute Function 


One very important function changes parts of lines selected by a con- 
text search within the line. 


(2)s<pattern> <replacement> <flags> 
substitute 


The s function replaces part of a line (selected by <pattern>) 
with <replacement>. It can best be read: 


Substitute for <pattern>, <replacement> 


The <pattern> argument contains a pattern, exactly like the 
patterns in addresses (see 2.2 above). The only difference 
between <pattern> and a context address is that the context 
address must be delimited by slash (‘/") characters; <pattern> 
may be delimited by any character other than space or new- 
line. 


By default, only the first string matched by <pattern> is 
replaced, but see the g flag below. 


The <replacement> argument begins immediately after the 
second delimiting character of <pattern>, and must be fol- 
lowed immediately by another instance of the delimiting char- 
acter. (Thus there are exactly three instances of the delimiting 
character.) 


The <replacement> is not a pattern, and the characters which 
are special in patterns do not have special meaning in 
<replacement>. Instead, other characters are special: 


& is replaced by the string matched by <pattern> 


\d (where d is a single digit) is replaced by the dth sub- 
string matched by parts of <pattern> enclosed in ‘\(’ 
and ‘\)’. If nested substrings occur in <pattern>, the 
dth is determined by counting opening delimiters ((\(’). 


As in patterns, special characters may be made literal 
by preceding them with backslash (‘\’). 
The <flags> argument may contain the following flags: 


g substitute <replacement> for all (non-overlapping) 
instances of <pattern> in the line. After a successful 
substitution, the scan for the next instance of <pattern> 
begins just after the end of the inserted characters; 
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ae) 


characters put into the line from <replacement> are not 
rescanned. 


print the line if a successful replacement was done. The 
p flag causes the line to be written to the output if and 
only if a substitution was actually made by the s func- 
tion. Notice that if several s functions, each followed 
by a p flag. successfully substitute in the same input 
line, output: one for each successful substitution. 


w <filename> 


Examples: 


write the line to a file if a successful replacement was 
done. The w flag causes lines which are actually substi- 
tuted by the s function to be written to a file named by 
<filename>. If <filename> exists before sed is run, it 
is overwritten; if not, it is created. 


A single space must separate w and <filename>. 


The possibilities of multiple, somewhat different copies 
of one input line being written are the same as for p. 


A maximum of 10 different file names may be men- 
tioned after w flags and w functions (see below), com- 
bined. 


The following command, applied to our standard input, 


s/to/by/w changes 


produces, on the standard output: 


In Xanadu did Kubhla Khan 

A stately pleasure dome decree: 
Where Alph, the sacred river, ran 
Through caverns measureless by man 
Down by a sunless sea. 


and, on the file “‘changes’’: 


Through caverns measureless by man 
Down by a sunless sea. 


If the nocopy option is in effect, the command: 


s/f..2:|/*P&*/gp 
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produces: 


A stately pleasure dome decree*P:* 
Where Alph*P,* the sacred river*P,* ran 
Down to a sunless sea*P.* 


Finally, to illustrate the effect of the g flag, the command: 
[X/s/an/ AN/p 


produces (assuming nocopy mode): 


In XANadu did Kubhla Khan 


and the command: 


/X/s/an/AN/gp 


produces: 
In XANadu did Kubhla KhAN 


3.3 Input-output Functions 


(2)p print 


The print function writes the addressed lines to the 
standard output file. They are written at the time 
the p function is encountered, regardless of what 
succeeding editing commands may do to the lines. 


(2)w write on <filename> 


<filen > : : 2 ; 
Ota The write function writes the addressed lines to the 


file named by <filename>. If the file previously 
existed, it is overwritten; if not, it is created. The 
lines are written exactly as they exist when the write 
function is encountered for each line, regardless of 
what subsequent editing commands may do to them. 


Exactly one space must separate the w and 
<filename>. 


A maximum of ten different files may be mentioned 
in write functions and w flags after s functions, com- 
bined. 
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(1)r 


<filename> 


NOTE 


read the contents of a file 


The read function reads the contents of <filename>, 
and appends them after the line matched by the 
address. The file is read and appended regardless of 
what subsequent editing commands do to the line 
which matched its address. If r and a functions are 
executed on the same line, the text from the a func- 
tions and the r functions is written to the output in 
the order that the functions are executed. 


Exactly one space must separate the r and 
<filename>. If a file mentioned by a r function 
cannot be opened, it is considered a null file, not an 
error, and no diagnostic is given. 


Since there is a limit to the number of files that can be opened 
simultaneously, care should be taken that no more than ten 
files be mentioned in w functions or flags; that number is 


reduced by one if any r functions are present. (Only one read 
file is open at one time.) 


Examples: 


Assume that the file ‘“‘notel’’ has the following contents: 


Note: Kubla Khan (more properly Kublai Khan; 1216-1294) 
was the grandson and most eminent successor of Genghiz 
(Chingiz) Khan, and founder of the Mongol dynasty in China. 


Then the following command: 


/Kubla/r notel 


produces: 


In Xanadu did Kubla Khan 
Note: Kubla Khan (more properly Kublai Khan; 1216-1294) 
was the grandson and most eminent successor of Genghiz 
(Chingiz) Khan, and founder of the Mongol dynasty in China. 

A stately pleasure dome decree: 

Where Alph, the sacred river, ran 

Through caverns measureless to man 


SED — A Non-interactive Text Editor 6—I3 


Down to a sunless sea. 


3.4 Multiple Input-line Functions 


Three functions, all spelled with capital letters, deal specially with 
pattern spaces containing imbedded newlines; they are intended prin- 
cipally to provide pattern matches across lines in the input. 


(2)N_ Next line 


The next input line is appended to the current line in the 
pattern space; the two input lines are separated by an imbed- 
ded newline. Pattern matches may extend across the imbed- 
ded newline(s). 


(2)D Delete first part of the pattern space 


Delete up to and including the first newline character in the 
current pattern space. If the pattern space becomes empty 
(the only newline was the terminal newline), read another 
line from the input. In any case, begin the list of editing 
commands again from its beginning. 


(2)P_ Print first part of the pattern space 


Print up to and including the first newline in the pattern 
space. 


The P and D functions are equivalent to their lower-case counterparts 
if there are no imbedded newlines in the pattern space. 


3.5 Hold and Get Functions 


Four functions save and retrieve part of the input for possible later 
use, 


(2)h hold pattern space 


The h functions copies the contents of the pattern space into 
a hold area (destroying the previous contents of the hold 
area). 


(2)H_ Hold pattern space 
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The H function appends the contents of the pattern space to 
_ the contents of the hold area; the former and new contents 
are separated by a newline. 


(2)g get contents of hold area 


The g function copies the contents of the hold area into the 
pattern space (destroying the previous contents of the pat- 
tern space). 


(2)G_ Get contents of hold area 


The G function appends the contents of the hold area to the 
contents of the pattern space; the former and new contents 
are separated by a newline. 


(2)x exchange 
The exchange command interchanges the contents of the 
pattern space and the hold area. 


Example: 


ae 


The commands 


th 

1s/ did.*// 
1x 

G 
s/\n/_:/ 


applied to our standard example, produce: 


In Xanadu did Kubla Khan :In Xanadu 

A stately pleasure dome decree: :In Xanadu 
Where Alph, the sacred river, ran :In Xanadu 
Through caverns measureless to man :In Xanadu 
Down to a sunless sea. :In Xanadu 
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3.6 Flow-of-control Functions 


These functions do no editing on the input lines, but control the 
application of functions to the lines selected by the address part. 


(2)! Don’t 


The Don’t command causes the next command (written 
on the same line), to be applied to all and only those 
input lines nor selected by the adress part. 


(2)£ Grouping 


The grouping command ‘{’ causes the next set of com- 
mands to be applied (or not applied) as a block to the 
input lines selected by the addresses of the grouping com- 
mand. The first of the commands under control of the 
grouping may appear on the same line as the ‘{* or on the 
next line. 


The group of commands is terminated by a matching ‘}’ 
standing on a line by itself. 


Groups can be nested. 


(0): place a label 


sHteey The label function marks a place in the list of editing 


commands which may be referred to by b and ¢ functions. 
The <label> may be any sequence of eight or fewer char- 
acters; if two different colon functions have identical 
labels, a compile time diagnostic will be generated, and no 
execution attempted. 


(2)b branch to label 


<label> : S25 
. The branch function causes the sequence of editing com- 


mands being applied to the current input line to be res- 
tarted immediately after the place where a colon function 
with the same <label> was encountered. If no colon 
function with the same label can be found after all the 
editing commands have been compiled, a compile time 
diagnostic is produced, and no execution is attempted. 


A b function with no <label> is taken to be a branch to 
the end of the list of editing commands; whatever should 


6—I6 Programmer's Guide: CTIX Supplement 


be done with the current input line is done, and another 
input line is read; the list of editing commands is restarted 
from the beginning on the new line. 


(2)t test substitutions 


< > : oe ae 
aes The ¢ function tests whether any successful substitutions 


have been made on the current input line; if so, it 
branches to <label>; if not, it does nothing. The flag 
which indicates that a successful substitution has been exe- 
cuted is reset by: 


1. reading a new input line, or 


2. executing ar function. 


3.7 Miscellaneous Functions 


(1)= equals 
The = function writes to the standard output the line 
number of the line matched by its address. 

(1)q quit 


The gq function causes the current line to be written to the 
output (if it should be), any appended or read text to be 
written, and execution to be terminated. 


Reference 


[1] Ken Thompson and Dennis M. Ritchie, The unix Programmer's 
Manual. Bell Laboratories, 1978. 


SED — A Non-interactive Text Editor 6—17 


7 


NROFF/TROFF User’s Manual 


Introduction 


NROFF and TROFF are text processors under the UNIX Time-Sharing 
System [1] that format text for typewriter-like terminals and for a 
Graphic Systems phototypesetter, respectively. (Device-independent 
TROFF, part of the Documenter’s Workbench, supports additional 
output devices.) They accept lines of text interspersed with lines of 
format control information and format the text into a printable, 
paginated document having a user-designed style. NROFF and TROFF 
offer unusual freedom in document styling, including: arbitrary style 
headers and footers; arbitrary style footnotes; multiple automatic 
sequence numbering for paragraphs, sections, etc; multiple column 
output; dynamic font and point-size control; arbitrary horizontal and 
vertical local motions at any point; and a family of automatic over- 
striking, bracket construction, and line drawing functions. 


NROFF and TROFF are highly compatible with each other and it is 
almost always possible to prepare input acceptable to both. Condi- 
tional input is provided that enables the user to embed input expressly 
destined for either program. NROFF can prepare output directly for a 
variety of terminal types and is capable of utilizing the full resolution 
of each terminal. 


Source: Joseph F. Ossanna (updated for 4.3BSD by Mark Seiden), NRorriTROFF 
User's Manual (Murray Hill, N.J.: Bell Laboratories, 1976). 
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Usage 


The general form of invoking NROFF (or TROFF) at UNIX command 
level is 


nroff options files (or troff options files) 


where options represents any of a number of option arguments and 
files represents the list of files containing the document to be format- 
ted. An argument consisting of a single minus (—) is taken to be a 
file name corresponding to the standard input. If no file names are 
given input is taken from the standard input. The options, which 
may appear in any order so long as they appear before the files, are: 


Option Effect 
-i Read standard input after the input files are 
exhausted. 
—mname Prepends the macro file /usrAib/tmac.name to the 
input files. 
—nN Number first generated page N. 
—olist Print only pages whose page numbers appear in list, 


which consists of comma-separated numbers and 
number ranges. A number range has the form 
N—-M and means pages N through M; a initial —-N 
means from the beginning to page N; and a final N— 
means from N to the end. 


—q Invoke the simultaneous input-output mode of the 
rd request. 

—-raN Number register a (one-character) is set to N. 

-sN Stop every N pages. NROFF will halt prior to every 


N pages (default N=1) to allow paper loading or 
changing, and will resume upon receipt of a new- 
line. TROFF will stop the phototypesetter every N 
pages, produce a trailer to allow changing cassettes, 
and will resume after the phototypesetter START 
button is pressed. 


-Z Efficiently suppress formatted output. Only pro- 
duce output to standard error (from tm requests or 
diagnostics). 
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NROFF Only 


-e Produce equally-spaced words in adjusted lines, 
using full terminal resolution. 


-h On output, use tabs during horizontal spacing to 
increase speed. Device tabs setting are assumed to 
be (and input tabs are initially set to) every 8 char- 
acter widths. 


-Tname Specifies the name of the output terminal type. 
Currently defined names are 37 for the (default) 
Model 37 Teletype®, tn300 for the GE Ter- 
miNet 300 (or any terminal without half-line capa- 
bilities), 300S for the DASI-300S, 300 for the DASI- 
300, and 450 for the DASI-450 (Diablo Hyterm). 


TROFF Only 

-a Send a printable (ASCII) approximation of the results 
to the standard output. 

-b TROFF will report whether the phototypesetter is 
busy or available. No text processing is done. 

-f Refrain from feeding out paper and stopping photo- 
typesetter at the end of the run. 

-t Direct output to the standard output instead of the 
phototypesetter. 

-w Wait until phototypesetter is available, if currently 
busy. 


Each option is invoked as a separate argument; for example, 
nroff —o4,8—/0 -T300S -mabc file! file2 


requests formatting of pages 4, 8, 9, and 10 of a document contained 
in the files named file/ and file2, specifies the output terminal as a 
DASI-300S, and invokes the macro package abc. 


Various pre- and post-processors are available for use with NROFF 
and TROFF. These include the equation preprocessors NEON and 
EQN [2] (for NROFF and TROFF respectively), and the table- 
construction preprocessor TBL [3]. A reverse-line postprocessor COL 
[4] is available for multiple-column NROFF output on terminals 
without reverse-line ability; COL expects the Model 37 Teletype escape 
sequences that NROFF produces by default. TK [4] is a 37 Teletype 
simulator postprocessor for printing NROFF output on a Tektronix 
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4014. Tc [4] is a phototypesetter-simulator postprocessor for TROFF 
that produces an approximation of phototypesetter output on a Tek- 
tronix 4014. For example, in 


tbl files | eqn | troff -t options | te 


the first | indicates the piping of TBL’s output to EQN’s input; the 
second the piping of EQN’s output to TROFF’s input; and the third 
indicates the piping of TROFF’s output to TC. 


The remainder of this manual consists of: a Summary and Outline; a 
Reference Manual keyed to the outline; and a set of Tutorial Exam- 
ples. Another tutorial is [5]. 


References 


[1] K.Thompson, D.M. Ritchie, UN/x Programmer's Manual, Sixth 
Edition (May 1975). 


[2] B. W. Kernighan, L. L. Cherry, Typesetting Mathematics— 
User’ s Guide (Second Edition), Bell Laboratories. 


[3] M. E. Lesk, Tbl—A Program to Format Tables, Bell Labora- 
tories internal memorandum. 


[4] Internal on-line documentation (man pages) on UNIX. 


[5] B. W. Kernighan, A TROFF Tutorial, Bell Laboratories. 
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Summary of Requests 


Font and Character Size Control 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

“psiNn 10 point previous Point size; also \s+N.t [See Note E] 

.fz F +N off - Font F to point size +N. [See Note E] 

fzSF +N off - Special Font characters to point size +N. 
[See Note E] 

.ss N 12/36em ignored Space-character size set to N/36em.t 
[See Note E] 

.cs FNM off - Constant character space (width) mode 
(font F).t [See Note P} 

-bd FN off - Embolden font F by N—1 units.t [See 
Note P]} 

bd SFN off - Embolden Special Font when current 
font is F.t [See Note P] 

ft F Roman previous Change to font F = x, xx, or 1-4. Also 
\fx, \f(xx, \fN. [See Note E] 

fp NF R,I,B,S ignored Font named F mounted on physical posi- 
tion 1SN<4. 

Page Control 

Request Initial If No 

Form Value* Argument Explanation & Notes* 

spl +N 1lin 1lin Page length. [See Note v] 

-bp +N N=1 - Eject current page; next page number N. 
[See Notes Bt,v] 

* Values separated by ";" are for NROFF and TROFF respectively. 

# Notes are explained at the end of this Summary. 

+ No effect in NROFF. 

+ The use of " ~ ™ as control character (instead of ".") suppresses the break 


function. 
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spn tN N=1 ignored Next page number N. 
«po +N 0; previous Page offset. [See Note v] 
26/27 in 
sane N - N=1V Need N vertical space (V = vertical spac- 
ing). [See Notes D,v] 


«mk R none internal Mark current vertical place in register R. 
[See Note D] 


wt tN none internal Return (upward only) to marked vertical 
place. [See Notes D,v] 


Text Filling, Adjusting and Centering 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

-br - - Break. [See Note B] 

fi iT] - Fill output lines. [See Notes B,E] 

-nf fill - No filling or adjusting of output lines. 
[See Notes B,E] 

.ad c adj, both adjust Adjust output lines with mode c. [See 
Note E] 

-na adjust = No output line adjusting. [See Note E] 

ceN off N=1 Center following N input text lines. [See 
Notes B,E] 

Vertical Spacing 

Request Initial If No 

Form Value* Argument _ Explanation & Notes* 

«vs N 1/6in;12pts —_ previous Vertical base line spacing (V). [See Notes 
E,p) 


* Values separated by ";" are for NROFF and TROFF respectively. 


Notes are explained at the end of this Summary. 
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Is N N=1 previous Output N—1 Vs after each text output 
line. [See Note E] 


sp N - N=1V Space vertical distance N in either direc- 
tion. [See Notes B,v] 

sv N - N=1V Save vertical distance N. [See Note v] 

0S - - Output saved vertical distance. 

-ns space - Turn no-space mode on. [See Note D] 

.rs - - Restore spacing; turn no-space mode off. 


[See Note D] 


Line Length and Indenting 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

JEN 6.5 in previous Line length. [See Notes E,m] 

win +N N=0 previous Indent. [See Notes B,E,m] 

ti tN - ignored Temporary indent. [See Notes B,E,m] 


Macros, Strings, Diversions and Position Traps 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

de xx yy - Jyy=. Define or redefine macro xx; end at call 
of yy. 

.am xx yy - y=. Append to a macro. 

-dS xx string - ignored Define a string xx containing string. 

.as xx string - ignored Append string to string xx. 

.rm xx - ignored Remove request, macro, or string. 

rn xx yy - ignored Rename request, macro, or string xx to 
a 

«di xx - end Divert output to macro xx. [See Note D] 

«da xx - end Divert and append to xx. [See Note D] 


* Values separated by ";" are for NROFF and TROFF respectively. 
Notes are explained at the end of this Summary. 
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wh N xx - - 

.ch xx N ~ - 

.dt N xx - off 
wit N xx - off 
em Xx none none 


Number Registers 


Set location trap; negative is w.r.t. page 
bottom. {See Note v] 


Change trap location. [See Note v] 
Set a diversion trap. [See Notes D,v] 
Set an input-line count trap. [See Note E] 


End macro is xx. 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

nmrRtNM - - Define and set number register R; auto- 
increment by M. [See Note u] 

safR oc arabic - Assign format to register R (c=1, i, I, a, 
A). 

aweR - - Remove register R. 


Tabs, Leaders and Fields 


Explanation & Notes* 


Request Initial If No 
Form Value* Argument 
sta Nt... 0.8; 0.Sin none 

wtec none none 

dec none 

fe ab off off 


Tab settings; left type, unless t=R(right), 
C(centered). [See Notes E,m] 


Tab repetition character. [See Note E] 
Leader repetition character. [See Note E] 


Set field delimiter a and pad character b. 


* Values separated by ";" are for NROFF and TROFF respectively. 
* Notes are explained at the end of this Summary. 
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Input and Output Conventions and Character Trans- 


lations 

Request Initial If No 

Form Value* Argument Explanation & Notes* 

OCC \ \ Set escape character. 

-e0 on - Turn off escape character mechanism. 

Ag N -5on on Ligature mode on if N>0. 

ul N off N=1 Underline (italicize in TROFF) N input 
lines. [See Note E] 

.cuN off N=1 Continuous underline in NROFF; like ul in 
TROFF. [See Note E] 

uf F Italic Italic Underline font set to F (to be switched to 
by ul). 

ccc Set control character to c. [See Note E] 

2c © = Set nobreak control character to c. [See 
Note E] 

tr abcd.... none - Translate a to b, etc. on output. [See 
Note O] 

Hyphenation 

Request Initial If No 

Form Value* Argument Explanation & Notes* 

-nh hyphenate = - No hyphenation. [See Note E] 

«hy N hyphenate hyphenate Hyphenate; N = mode. [See Note E] 

«he ¢ \% \% Hyphenation indicator character c. [See 
Note E} 

-hw word! ... ignored Exception words. 


* Values separated by ";" are for NROFF and TROFF respectively. 
Notes are explained at the end of this Summary. 
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Three Part Titles 


Request Initial 
Form Value* 


If No 
Argument Explanation & Notes* 


«tl “left “center “right ~ - 
spec % 
Jt £N 6.5in 


- Three part title. 
off Page number character. 


previous Length of title. [See Notes E,m] 


Output Line Numbering 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

am tNMSI - off Number mode on or off, set parame- 
ters. [See Note E] 

nn N - N=1 Do not number next N lines. [See 
Note E] 

Conditional Acceptance of Input 


Request Form 


Explanation & Notes* 


wif c anything 


wif !c anything 
if N anything 
if !N anything 


if “string] *string2 ° anything 
if! “string] *string2 ° anything 


ie c anything 


el anything 


If condition c true, accept anything as input, for 
multi-line use \{anything \}. 


If condition c false, accept anything. 
If expression N > 0, accept anything. [See Note u] 


If expression N = 0, accept anything. [See Note 
ul 


If string] identical to string2, accept anything. 
If string] not identical to string2, accept anything. 


If portion of if-else; all above forms (like if). [See 
Note u] 


Else portion of if-else. 


* Values separated by ";" are for NROFF and TROFF respectively. 


* Notes are explained at the end 
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Environment Switching 


Request Initial If No 
Form Value* Argument Explanation & Notes* 
ev N N=0 previous Environment switched (push down). 


Insertions from the Standard Input 


Request Initial If No 

Form Value* Argument Explanation & Notes* 
“rd prompt - prompt=BEL __ Read insertion. 

eX - - Exit from NROFF/TROFF. 


Input/Output File Switching 


Request Initial If No 

Form Value* Argument Explanation & Notes* 

.So filename - - Switch source file (push down). 

nx filename - end-of-file | Next file. 

spi program - - Pipe output to program (NROFF only). 

Miscellaneous 

Request Initial If No 

Form Value* Argument Explanation & Notes* 

-mecN : off Set margin character c and separation N. 
[See Notes E,m] 

.tm string - newline Print string on terminal (UNIX standard 
error output). 

ig yy - Lys. Ignore till call of yy. 


* Values separated by ";" are for NROFF and TROFF respectively. 
Notes are explained at the end of this Summary. 
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-pm t - all Print macro names and sizes; if ¢ present, 
print only total of sizes. 


ab string - - Print a message and abort. 
fl - - Flush output buffer. [See Note B] 
Notes 
B Request normally causes a break. 
D Mode or relevant parameters associated with current 
diversion level. 
E Relevant parameters are a part of the current environ- 
ment. 
O Must stay in effect until logical output. 
P Mode must be still or again in effect at the time of phy- 


sical output. 


y,p,m,u Default scale indicator; if not specified, scale indicators 
are ignored. 


Alphabetical Request and Section Number Cross Reference 


ab 20 ¢2 10 di 7 cx 18 hwil3 Ig 10 ne 3 os 5 rd 18 ss 2 uf 10 
ad 4 cc 10 ds 7 fe 9 hy 13 li 10 nf 4 pe 14 rm 7 sv 5 ul 10 
af 8 ce 4 dt 7 fi 4 ie 16 L 6 nhi13 pi 19 m 7 ta 9 vs 5 
am 7 ch 7 cc 10 fl 20 if 16 ‘ts S nmiIS pl 3 mw 8&8 te 9 wh 7 
as 7 cs 2 el 16 fp 2 ig 20 It 14 mon 15 pm20 ms 5 ti 6 
bd 2 cu 10 em 7 ft 2 in 6 mce20 mor 8 pn 3 mt 3 Ww 14 
bp 3 da 7 co 10 fe 2 it 7 mk 3 ns S po 3 so 19° tm 20 
br 4 de 7 ev 17 he 13) Ie 9 na 4 nx 19 ps 2 sp S w 10 
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Escape Sequences for Characters, Indicators, and Functions 


Section Escape 


Reference Sequence Meaning 
10.1 \\ \ (to prevent or delay the interpretation of \ ) 
10.1 \e Printable version of the current escape character. 
21 No (acute accent); equivalent to \(aa 
2.1 \ ~ (grave accent); equivalent to \(ga 
2.1 \- — Minus sign in the current font 
7 \. Period (dot) (see de) 
11.1 \(space) Unpaddable space-size space character 
11.1 \o Digit width space 
11.1 ‘il 1/6em narrow space character (zero width in NROFF) 
11.1 \7 1/12 em half-narrow space character (zero width in 
NROFE) 
4.1 \& Non-printing, zero width character 
10.6 \! Transparent line indicator 
10.7 \" Beginning of comment 
7.3 \SN Interpolate argument 1=N=9 
13 \% Default optional hyphenation character 
2.1 \Qx Character named xx 
71 \*x, \*Qcx Interpolate string x or xx 
9.1 \a Non-interpreted leader character 
12.3 \b ‘abc... ” Bracket building function 
4.2 \c Interrupt text processing 
11.1 \d Forward (down) 1/2 em vertical motion (1/2 line in 
NROFF) 
2.2 \fx,\f(xx,\f£N Change to font named x or xx, or position NV 
11.1 \h‘N * Local horizontal motion; move right N (negative left) 
11.3 \kx Mark horizontal input place in register x 
12.4 \l “Ne * Horizontal line drawing function (optionally with c ) 
12.4 \L “Ne * Vertical line drawing function (optionally with c) 
8 \nx, \nQcx Interpolate number register x or xx 
12.1 \o‘ abe...” Overstrike characters a, b, ¢, ... 
4.1 \p Break and spread output line 
11.1 \r Reverse 1em vertical motion (reverse line in NROFF) 
2:3 \sN, \S£N Point-size change function 
9.1 \t Non-interpreted horizontal tab 
11.1 \u Reverse (up) 1/2 em vertical motion (1/2 line in NROFF) 
11.1 \v-N * Local vertical motion; move down N (negative up) 
11.2 \w ‘string ~ Interpolate width of string 
5.2 \x°N * Extra line-space function (negative before, positive after) 
12.2 \zc Print c with zero width (without spacing) 
16 \f Begin conditional input 
16 \} End conditional input 
10.7 \(newline) Concealed (ignored) newline 
- \X X, any character not listed above 


The escape sequences \\, \., \", \$, \*, \a, \n, \t, and \(new- 
line) are interpreted in copy mode (§7.2). 
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Predefined General Number Registers 


Section 
Reference 


3 
19 
11.2 

7.4 

7.4 


Register 
Name 


Description 


Current page number. 

Number of lines read from current input file. 

Character type (set by width function). 

Width (maximum) of last completed diversion. 

Height (vertical size) of last completed diversion. 

Current day of the week (1-7). 

Current day of the month (1-31). 

Current horizontal place on input line (not in ditroff) 

Output line number. 

Current month (1-12). 

Vertical position of last printed text base-line. 

Depth of string below base line (generated by width function). 
Height of string above base line (generated by width function). 
Last two digits of current year. 


Predefined Read-Only Number Registers 


Section 
Reference 


ia 


Register 
Name 


Reb eut babe 


Nee ZS ER ODOR ORGS 


Description 


Number of arguments available at the current macro level. 
Set to 1 in TROFF, if -a option used; always 1 in NROFF. 
Available horizontal resolution in basic units. 

Set to current line-spacing (Is) parameter 

Set to 1 if the current page is being printed; otherwise 0. 

Set to 1 in NROFF, if -T option used; always 0 in TROFF. 
Available vertical resolution in basic units. 

Post-line extra line-space most recently utilized using \x“N ~. 
Number of lines read from current input file. 

Current vertical place in current diversion; equal to nl, if no 
diversion. 

Current font as physical quadrant (1-4). 

Text base-line high-water mark on current page or diversion. 
Current indent. 

Current adjustment mode and type. 

Length of text portion on current partial output line. 
Current line length. 

Length of text portion on previous output line. 

Current page offset. 

Current page length. 

Current point size. 

Distance to the next trap. 

Equal to 1 in fill mode and 0 in nofill mode. 

Current vertical line spacing. 

Width of previous character. 

Reserved version-dependent register. 

Reserved version-dependent register. 

Name of current diversion. 
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Reference Manual 


1. General Explanation 
1.1 Form of Input 


Input consists of text lines, which are destined to be printed, inter- 
spersed with control lines, which set parameters or otherwise control 
subsequent processing. Control lines begin with a control character— 
normally . (period) or ~ (acute accent)—followed by a one or two 
character name that specifies a basic request or the substitution of a 
user-defined macro in place of the control line. The control character 
“ suppresses the break function—the forced output of a partially filled 
line—caused by certain requests. The control character may be 
separated from the request/macro name by white space (spaces and/or 
tabs) for sthetic reasons. Names must be followed by either space or 
newline. Control lines with unrecognized names are ignored. 


Various special functions may be introduced anywhere in the input by 
means of an escape character, normally \. For example, the function 
\nR causes the interpolation (insertion in place) of the contents of the 
number register R in place of the function; here R is either a single 
character name as in \nx, or left-parenthesis-introduced, two- 
character name as in \n(xx. 


1.2 Formatter and Device Resolution 


TROFF internally uses 432 units/inch, (for historical reasons, 
corresponding to the Graphic Systems phototypesetter which had a 
horizontal resolution of 1/432 inch and a vertical resolution of 1/144 
inch.) NROFF internally uses 240 units/inch, corresponding to the 
least common multiple of the horizontal and vertical resolutions of 
various _typewriter-like output devices. TROFF rounds 
horizontal/vertical numerical parameter input to its own internal 
horizontal/vertical resolution. NROFF similarly rounds numerical 
input to the actual resolution of the output device indicated by the 
—T option (default Model 37 Teletype). 
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1.3 Numerical Parameter Input 


Both NROFF and TROFF accept numerical input with the scale indica- 
tor suffixes shown in the following table, where S is the current type 
size in points, V is the current vertical line spacing in basic units, and 
C is a nominal character width in basic units. 


Scale Number of basic units 

Indicator | Meaning TROFF NROFF 

i Inch 432 240 

c Centimeter 432 50/127 | 240xS0/127 

Pp Pica = 1/6 inch 72 240/6 

m Em = S points 6x Cc 

n En = Em/2 3xS C, same as Em 

p Point = 1/72 inch 6 240/72 

u Basic unit 1 1 

v Vertical line space | V V 

Default, see below 


In NROFF, both the em and the en are taken to be equal to the C, 
which is output-device dependent; common values are 1/10 and 1/12 
inch, Actual character widths in NROFF need not be all the same and 
constructed characters such as —> (-) are often extra wide. The 
default scaling is ems for the horizontally-oriented requests and func- 
tions Il, in, ti, ta, It, po, me, \h, and \l; Vs for the vertically- 
oriented requests and functions pl, wh, ch, dt, sp, sv, ne, rt, \v, \x, 
and \L; p for the vs request; and u for the requests nr, if, and ie. 
All other requests ignore any scale indicators. When a number regis- 
ter containing an already appropriately scaled number is interpolated 
to provide numerical input, the unit scale indicator u may need to be 
appended to prevent an additional inappropriate default scaling. The 
number, NV, may be specified in decimal-fraction form but the param- 
eter finally stored is rounded to an integer number of basic units. 


The absolute position indicator | may be prefixed to a number N to 
generate the distance to the vertical or horizontal place N. For 
vertically-oriented requests and functions, | N becomes the distance in 
basic units from the current vertical place on the page or in a diver- 
sion (§7.4) to the vertical place N. For all other requests and func- 
tions, | N becomes the distance from the current horizontal place on 
the input line to the horizontal place N. For example, 


sp | 3.2¢ 
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will space in the required direction to 3.2 centimeters from the top of 
the page. 


1.4 Numerical Expressions 


Wherever numerical input is expected, an expression involving 
parentheses, the arithmetic operators +, —, /, *, % (mod), and the 
logical operators <, >, <=, >=, = (or ==), . (and), : (or) may be 
used. Except where controlled by parentheses, evaluation of expres- 
sions is left-to-right; there is no operator precedence. In the case of 
certain requests, an initial + or — is stripped and interpreted as an 
increment or decrement indicator respectively. In the presence of 
default scaling, the desired scale indicator must be attached to every 
number in an expression for which the desired and default scaling 
differ. For example, if the number register x contains 2 and the 
current point size is 10, then 


ll (4.25i+ \nxP + 3)/2u 


will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 30 
points. 


1.5 Notation 


Numerical parameters are indicated in this manual in two ways. +N 
means that the argument may take the forms N, +N, or —N and that 
the corresponding effect is to set the affected parameter to N, to 
increment it by N, or to decrement it by N respectively. Plain N 
means that an initial algebraic sign is not an increment indicator, but 
merely the sign of N. Generally, unreasonable numerical input is 
either ignored or truncated to a reasonable value. For example, most 
requests expect to set parameters to non-negative values; exceptions 
are sp, wh, ch, nr, and if. The requests ps, ft, po, vs, Is, ll, in, and 
It restore the previous parameter value in the absence of an argument. 


Single character arguments are indicated by single lower case letters 
and one/two character arguments are indicated by a pair of lower case 
letters. Character string arguments are indicated by multi-character 
mnemonics. 
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2. Font and Character Size Control 
2.1 Character Set 


The TROFF character set consists of a typesetter-dependent basic char- 
acter set plus a Special Mathematical Font character set—each having 
102 characters. An example of these character sets is shown in the 
Appendix Table I. All printable ASCII characters are included, with 
some on the Special Font. With three exceptions, these ASCII charac- 
ters are input as themselves, and non-ASCII characters are input in 
the form \(xx where xx is a two-character name given in the Appen- 
dix Table II. The three ASCII exceptions are mapped as follows: 


ASCII Input Printed by TROFF 
Character Name Character Name 
° acute accent t close quote 
° grave accent ‘ open quote 
- minus - hyphen 


The characters “, ~, and — may be input by \~, \~, and \— respec- 
tively or by their names (Table IT). The ASCII characters @, #, ", “, 
~,<,>,\, €, }, ~, 7, and _ exist only on the Special Font and are 
printed as a 1-em space if that font is not mounted. 


NROFF understands the entire TROFF character set, but can in general 
print only ASCII characters, additional characters as may be available 
on the output device, such characters as may be able to be con- 
structed by overstriking or other combination, and those that can rea- 
sonably be mapped into other printable characters. The exact 
behavior is determined by a driving table prepared for each device. 
The characters *, ~, and _ print as themselves. 


2.2 Fonts 


The default mounted fonts are Times Roman (R), Times Italic (I), 
Times Bold (B), and the Special Mathematical Font (S) on physical 
typesetter positions 1, 2, 3, and 4 respectively. These fonts are used 
in this document. The current font, initially Roman, may be changed 
(among the mounted fonts) by use of the ft request, or by imbedding 
at any desired point either \fx, \f(xx, or \fN where x and xx are the 
name of a mounted font and N is a numerical font position. It is nor 
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necessary to change to the Special Font; characters on that font are 
automatically handled. A request for a named but not-mounted font 
is ignored. TROFF can be informed that any particular font is 
mounted by use of the fp request. The list of known fonts is installa- 
tion dependent. In the subsequent discussion of font-related requests, 
F represents either a one/two-character font name or the numerical 
font position, 1-4. The current font is available (as numerical posi- 
tion) in the read-only number register .f. 


NROFF understands font control and normally underlines Italic char- 
acters (see §10.5). 


2.3 Character Size 


Character point sizes available are typesetter dependent, but often 
include 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. 
This is a range of 1/12 inch to 1/2 inch. The ps request is used to 
change or restore the point size. Alternatively the point size may be 
changed between any two characters by imbedding a \sN at the 
desired point to set the size to N, or a \stN (1SN9) to 
increment/decrement the size by N; \s0 restores the previous size. 
Requested point size values that are between two valid sizes yield the 


larger of the two. The current size is available in the .s register. 
NROFF ignores type size control. 


Request Initial If No 
Form Value Argument Explanation & Notes* 
-ps +N 10 point previous Point size set to +N. Alternatively 


imbed \sN or \s+N. Any positive size 
value may be requested; if invalid, the 
next larger valid size will result, with a 
maximum of 36. A paired sequence 
+N, —N will work because the previous 
requested value is also remembered. 
Ignored in NROFF. [See Note E] 


Notes are explained at the end of the Summary above. 
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.f2F tN 


2S F +N 


ss N 


cs FNM 


-bd FN 


-bdSFN 


off 


off 


12/36em 


off 


off 


off 


ignored 


The characters in font F will be adjusted 
to be in size +N. Characters in the Spe- 
cial Font encountered during the use of 
font F will have the same size modifi- 
cation. (Use the .fz S request if different 
treatment of Special Font characters is 
required). .fz must follow any .fp request 
for the position. [See Note E] 


The characters in the Special Font will 
be in size +N independent of previous .fz 
requests. [See Note E] 


Space-character size is set to N/36ems. 
This size is the minimum word spacing in 
adjusted text. Ignored in NROFF. [See 
Note E] 


Constant character space (width) mode is 
set on for font F (if mounted); the width 
of every character will be taken to be 
N/36 ems. If M is absent, the em is that 
of the character’s point size; if M is 
given, the em is M-points. All affected 
characters are centered in this space, in- 
cluding those with an actual width larger 
than this space. Special Font characters 
occurring while the current font is F are 
also so treated. If N is absent, the mode 
is turned off. The mode must be still or 
again in effect when the characters are 
physically printed. Ignored in NROFF. 
[See Note P] 


The characters in font F will be artifi- 
cially emboldened by printing each one 
twice, separated by N—1 basic units. A 
reasonable value for N is 3 when the 
character size is in the vicinity of 10 
points. If N is missing the embolden 
mode is turned off. The mode must be 
still or again in effect when the charac- 
ters are physically printed. Ignored in 
NROFF. [See Note P] 


The characters in the Special Font will 
be emboldened whenever the current 
font is F. The mode must be still or 
again in effect when the characters are 
physically printed. [See Note P] 


7—20 Programmer’s Guide: CTIX Supplement 


ft F Roman previous Font changed to F. Alternatively, imbed 
\fF. The font name P is reserved to 
mean the previous font. [See Note E] 


fp N F R,I,B,S ignored Font position. This is a statement that a 
font named F is mounted on position NV 
(1-4). It is a fatal error if F is not 
known. The phototypesetter has four 
fonts physically mounted. Each font con- 
sists of a film strip which can be mounted 
on a numbered quadrant of a wheel. The 
default mounting sequence assumed by 
TROFF is R, I, B, and S on positions 1, 2, 
3 and 4. 


3. Page Control 


Top and bottom margins are not automatically provided; it is conven- 
tional to define two macros and to set traps for them at vertical posi- 
tions 0 (top) and —N (N from the bottom). See §7 and Tutorial 
Examples §T2. A pseudo-page transition onto the first page occurs 
either when the first break occurs or when the first non-diverted text 
processing occurs. Arrangements for a trap to occur at the top of the 
first page must be completed before this transition. In the following, 
references to the current diversion (§7.4) mean that the mechanism 
being described works during both ordinary and diverted output (the 
former considered as the top diversion level). 


The usable page width on the Graphic Systems phototypesetter was 
about 7.54 inches, beginning about 1/27 inch from the left edge of the 
8 inch wide, continuous roll paper, but these characteristics are 
typesetter-dependent. The physical limitations on NROFF output are 
output-device dependent. 
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Request Initial 
Form Value 


If No 
Argument 


Explanation & Notes* 


plh+N  11in 


-bp +N N=1 


~pn tN N=1 


spo tN 0; 
26/27 int 


ne N - 


‘mk R none 


* 


11in 


ignored 


previous 


internal 


Page length set to +N. The internal limitation is 
about 75 inches in TROFF and about 136 inches in 
NROFF. The current page length is available in 
the .p register. [See Note v] 


Begin page. The current page is ejected and a 
new page is begun. If +N is given, the new page 
number will be +N. Also see request ns. [See 
Notes B*,y] 


Page number. The next page (when it occurs) 
will have the page number +N. A pn must occur 
before the initial pseudo-page transition to affect 
the page number of the first page. The current 
page number is in the % register. 


Page offset. The current left margin is set to +N. 
The TROFF initial value provides about 1 inch of 
paper margin including the physical typesetter 
margin of 1/27 inch. In TROFF the maximum 
(line-length)+ (page-offset) is about 7.54 inches. 
See §6. The current page offset is available in 
the .o register. [See Note v] 


Need N vertical space. If the distance, D, to the 
next trap position (see §7.5) is less than N, a for- 
ward vertical space of size D occurs, which will 
spring the trap. If there are no remaining traps 
on the page, D is the distance to the bottom of 
the page. If D< V, another line could still be 
output and spring the trap. In a diversion, D is 
the distance to the diversion trap, if any, or is 
very large. [See Notes D,v] 


Mark the current vertical place in an internal 
register (both associated with the current diver- 
sion level), or in register R, if given. See rt 
request. [See Note D] 


Notes are explained at the end of the Summary above. 


‘The use of " ° “ as control character (instead of ".") suppresses the break function. 
t Values separated by ";" are for NROFF and TROFF respectively. 
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“rt +N none internal Return upward only to a marked vertical place in 
the current diversion. If +N (w.r.t. current 
place) is given, the place is +N from the top of 
the page or diversion or, if N is absent, to a place 
marked by a previous mk. Note that the sp 
request (§5.3) may be used in all cases instead of 
rt by spacing to the absolute place stored in a 
explicit register; e. g. using the sequence .mk R 

. .sp \nRu. [See Notes D,v] 


4. Text Filling, Adjusting and Centering 


4.1 Filling and Adjusting 


Normally, words are collected from input text lines and assembled 
into a output text line until some word doesn’t fit. An attempt is 
then made to hyphenate the word to assemble a part of it into the 
output line. The spaces between the words on the output line are 
then increased to spread out the line to the current line length minus 
any current indent. A word is any string of characters delimited by 
the space character or the beginning/end of the input line. Any adja- 
cent pair of words that must be kept together (neither split across out- 
put lines nor spread apart in the adjustment process) can be tied 
together by separating them with the unpaddable space character 
" \" (backslash-space). The adjusted word spacings are uniform in 
TROFF and the minimum interword spacing can be controlled with 
the ss request (§2). In NROFF, they are normally nonuniform 
because of quantization to character-size spaces; however, the com- 
mand line option -e causes uniform spacing with full output device 
resolution. Filling, adjustment, and hyphenation ($13) can all be 
prevented or controlled. The text length on the last line output is 
available in the .n register, and text base-line position on the page for 
this line is in the nl register. The text base-line high-water mark 
(lowest place) on the current page is in the .h register. The .k register 
(read-only) contains the horizontal size of the text portion (without 
indent) of the current partially-collected output line (if any) in the 
current environment. 


An input text line ending with ., ?, or ! is taken to be the end of a 
sentence, and an additional space character is automatically provided 
during filling. Multiple inter-word space characters found in the 
input are retained, except for trailing spaces; initial spaces also cause 
a break. 
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When filling is in effect, a \p may be imbedded or attached to a 
word to cause a break at the end of the word and have the resulting 
output line spread out to fill the current line length. 


A text input line that happens to begin with a control character 
($10.4) can be made to not look like a control line by preceding it by 
the non-printing, zero-width filler character \&. Still another way is 
to specify output translation of some convenient character into the 
control character using tr (§10.5). 


4.2 Interrupted Text 


The copying of a input line in nofill (non-fill) mode can be interrupted 
by terminating the partial line with a \c. The next encountered input 
text line will be considered to be a continuation of the same line of 
input text. Similarly, a word within filled text may be interrupted by 
terminating the word (and line) with \c; the next encountered text 
will be taken as a continuation of the interrupted word. If the inter- 
vening control lines cause a break, any partial line will be forced out 
along with any partial word. 


Request _ Initial If No 


Form Value Argument Explanation & Notes* 
-br - - Break. The filling of the line currently being 


collected is stopped and the line is output 
without adjustment. Text lines beginning 
with space characters and empty text lines 
(blank lines) also cause a break. [See Note B] 


fi fill on - Fill subsequent output lines. The register .u 
is 1 in fill mode and 0 in nofill mode. [See 
Notes B,E] 

nf fill on - Nofill. Subsequent output lines are neither 


filled nor adjusted. Input text lines are 
copied directly to output lines without regard 
for the current line length. [See Notes B,E] 


* Notes are explained at the end of the Summary above. 
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.ad c adj,both adjust Line adjustment is begun. If fill mode is not 
on, adjustment will be deferred until fill 
mode is back on. If the type indicator c is 
present, the adjustment type is changed as 
shown in the following table. The type indi- 
cator can also be a value saved from the 
read-only .j number register, which is set to 
contain the current adjustment mode and 
type. [See Note E] 


Indicator Adjust Type 
adjust left margin only 
adjust right margin only 
center 

adjust both margins 


unchanged 


na adjust - Noadjust. Adjustment is turned off; the right 
margin will be ragged. The adjustment type 
for ad is not changed. Output line filling still 
occurs if fill mode is on. [See Note E] 


.ce N off N=1 Center the next N input text lines within the 
current (line-length minus indent). If N=0, 
any residual count is cleared. A break occurs 
after each of the N input lines. If the input 
line is too long, it will be left adjusted. [See 
Notes B,E] 


5. Vertical Spacing 
5.1 Base-line Spacing 


The vertical spacing (V) between the base-lines of successive output 
lines can be set using the vs request with a resolution of 
1/144 inch = 1/2 point in TROFF, and to the output device resolution 
in NROFF. V must be large enough to accommodate the character 
sizes on the affected output lines. For the common type sizes (9-12 
points), usual typesetting practice is to set V to 2 points greater than 
the point size; TROFF default is 10-point type on a 12-point spacing 
(as in this document). The current V is available in the .v register. 
Multiple-V line separation (e.g. double spacing) may be requested 
with ls. 
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5.2 Extra Line-space 


If a word contains a vertically tall construct requiring the output line 
containing it to have extra vertical space before and/or after it, the 
extra-line-space function \x“N ~ can be imbedded in or attached to 
that word. In this and other functions having a pair of delimiters 
around their parameter (here ~), the delimiter choice is arbitrary, 
except that it can’t look like the continuation of a number expression 
for N. If N is negative, the output line containing the word will be 
preceded by N extra vertical space; if N is positive, the output line 
containing the word will be followed by N extra vertical space. If suc- 
cessive requests for extra space apply to the same line, the maximum 
values are used. The most recently utilized post-line extra line-space 
is available in the .a register. 


5.3 Blocks of Vertical Space 


A block of vertical space is ordinarily requested using sp, which 
honors the no-space mode and which does not space past a trap. A 
contiguous block of vertical space may be reserved using sv. 


Request Initial If No 
Form Value Argument Explanation & Notes* 
.ws N 1/6in, previous Set vertical base-line spacing size V. Tran- 
12ptst sient extra vertical space available with 
\x“N ~ (see above). [See Notes E,p] 
ls N N=1 previous Line spacing set to +N. N—-1 Vs (blank lines) 


are appended to each output text line. The 
(read-only) number register .L is set to con- 
tain the current line-spacing value. 
Appended blank lines are omitted, if the text 
or previous appended blank line reached a 
trap position. [See Note E]} 


* 


Notes are explained at the end of the Summary above. 
t Values separated by ";" are for NROFF and TROFF respectively. 
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spNn - N=1V Space vertically in either direction. If N is 
negative, the motion is backward (upward) 
and is limited to the distance to the top of the 
page. Forward (downward) motion is trun- 
cated to the distance to the nearest trap. If 
the no-space mode is on, no spacing occurs 
(see ns, and rs below). [See Notes B,v] 


sv N - N=1V Save a contiguous vertical block of size N. If 
the distance to the next trap is greater than N, 
N vertical space is output. No-space mode 
has no effect. If this distance is less than N, 
no vertical space is immediately output, but 
N is remembered for later output (see os). 
Subsequent sv requests will overwrite any still 
remembered N. [See Note v] 


OS - - Output saved vertical space. No-space mode 
has no effect. Used to finally output a block 
of vertical space requested by an earlier sv 
request. 


ns space - No-space mode turned on. When on, the 
no-space mode inhibits sp requests and bp 
requests without a next page number. The 
no-space mode is turned off when a line of 
output occurs, or with rs. [See Note D] 


.rs space - Restore spacing. The no-space mode is 
turned off. [See Note D} 

Blank Causes a break and outputs a blank line just 

text like sp 1. [See Note B] 

line. 


6. Line Length and Indenting 


The maximum line length for fill mode may be set with Il. The 
indent may be set with in; an indent applicable to only the next output 
line may be set with ti. The line length includes indent space but not 
page offset space. The line-length minus the indent is the basis for 
centering with ce. The effect of Il, in, or ti is delayed, if a partially 
collected line exists, until after that line is output. In fill mode the 
length of text on an output line is less than or equal to the line length 
minus the indent. The current line length and indent are available in 
registers .| and .i respectively. The length of three-part titles pro- 
duced by tl (see §14) is independently set by It. 
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Request Initial If No 
Form Value Argument Explanation & Notes* 


AN 6.5in previous Line length is set to +N. In TROFF the 
maximum (line-length)+(page-offset) is about 
7.54 inches. [See Notes E,m] 


din tN N=0 previous Indent is set to +N. The indent is 
prepended to each output line. [See 
Notes B,E,m] 


tht - ignored Temporary indent. The next output text 
line will be indented a distance +N with 
respect to the current indent. The result- 
ing total indent may not be negative. 
The current indent is not changed. [See 
Notes B,E,m] 


7. Macros, Strings, Diversions and Position 
Traps 


7.1 Macros and Strings 


A macro is a named set of arbitrary lines that may be invoked by 
name or with a trap. A string is a named string of characters, not 
including a newline character, that may be interpolated by name at 
any point. Request, macro, and string names share the same name 
list. Macro and string names may be one or two characters long and 
may usurp previously defined request, macro, or string names. Any 
of these entities may be renamed with rn or removed with rm. Mac- 
ros are created by de and di, and appended to by am and da; di and 
da cause normal output to be stored in a macro. Strings are created 
by ds and appended to by as. A macro is invoked in the same way as 
a request; a control line beginning .xx will interpolate the contents of 
macro xx. The remainder of the line may contain up to nine argu- 
ments. The strings x and xx are interpolated at any desired point with 
\*x and \*(xx respectively. String references and macro invocations 
may be nested. 


* 


Notes are explained at the end of the Summary above. 
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7.2 Copy Mode Input Interpretation 


During the definition and extension of strings and macros (not by 
diversion) the input is read in copy mode. The input is copied 
without interpretation excepr that: 


e The contents of number registers indicated by \n are interpo- 
lated. 


e Strings indicated by \* are interpolated. 
e Arguments indicated by \$ are interpolated. 


Concealed newlines indicated by \(newline) are eliminated. 
e Comments indicated by \" are eliminated. 


e \t and \a are interpreted as ASCII horizontal tab and SOH 
respectively (§9). 


e \\ is interpreted as \. 
e \. is interpreted as ".". 


These interpretations can be suppressed by prepending a \. For 
example, since \\ maps into a \, \\n will copy as \n which will be 
interpreted as a number register indicator when the macro or string is 
reread. 


7.3 Arguments 


When a macro is invoked by name, the remainder of the line is taken 
to contain up to nine arguments. The argument separator is the 
space character, and arguments may be surrounded by double-quotes 
to permit imbedded space characters. Pairs of double-quotes may be 
imbedded in double-quoted arguments to represent a single double- 
quote. If the desired arguments won’t fit on a line, a concealed new- 
line may be used to continue on the next line. 


When a macro is invoked the input level is pushed down and any argu- 
ments available at the previous level become unavailable until the 
macro is completely read and the previous level is restored. A 
macro’s own arguments can be interpolated at any point within the 
macro with \$N, which interpolates the Nth argument (ISN=9). If 
an invoked argument doesn’t exist, a null string results. For example, 
the macro xx may be defined by 
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.de xx \ "begin definition 
Today is \\$1 the \\$2. 
a \"end definition 


and called by 
.xx Monday 14th 
to produce the text 
Today is Monday the 14th. 


Note that the \$ was concealed in the definition with a prepended \. 
The number of currently available arguments is in the .$ register. 


No arguments are available at the top (non-macro) level in this imple- 
mentation. Because string referencing is implemented as a input-level 
push down, no arguments are available from within a string. No 
arguments are available within a trap-invoked macro. 


Arguments are copied in copy mode onto a stack where they are avail- 
able for reference. The mechanism does not allow an argument to 
contain a direct reference to a long string (interpolated at copy time) 
and it is advisable to conceal string references (with an extra \) to 
delay interpolation until argument reference time. 


7.4 Diversions 


Processed output may be diverted into a macro for purposes such as 
footnote processing (see Tutorial §TS) or determining the horizontal 
and vertical size of some text for conditional changing of pages or 
columns. A single diversion trap may be set at a specified vertical 
position. The number registers dn and dl respectively contain the 
vertical and horizontal size of the most recently ended diversion. 
Processed text that is diverted into a macro retains the vertical size of 
each of its lines when reread in nofill mode regardless of the current 
V. Constant-spaced (cs) or emboldened (bd) text that is diverted can 
be reread correctly only if these modes are again or still in effect at 
reread time. One way to do this is to imbed in the diversion the 
appropriate cs or bd requests with the transparent mechanism 
described in §10.6. 


Diversions may be nested and certain parameters and registers are 
associated with the current diversion level (the top non-diversion level 
may be thought of as the Oth diversion level). These are the diver- 
sion trap and associated macro, no-space mode, the internally-saved 
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marked place (see mk and rt), the current vertical place (.d register), 
the current high-water text base-line (.h register), and the current 
diversion name (.z register). 


7.5 Traps 


Three types of trap mechanisms are available—page traps, a diversion 
trap, and an input-line-count trap. Macro-invocation traps may be 
planted using wh at any page position including the top. This trap 
position may be changed using ch. Trap positions at or below the 
bottom of the page have no effect unless or until moved to within the 
page or rendered effective by an increase in page length. Two traps 
may be planted at the same position only by first planting them at dif- 
ferent positions and then moving one of the traps; the first planted 
trap will conceal the second unless and until the first one is moved 
(see Tutorial Examples §T5). If the first one is moved back, it again 
conceals the second trap. The macro associated with a page trap is 
automatically invoked when a line of text is output whose vertical size 
reaches or sweeps past the trap position. Reaching the bottom of a 
page springs the top-of-page trap, if any, provided there is a next 
page. The distance to the next trap position is available in the .t 
register; if there are no traps between the current position and the 
bottom of the page, the distance returned is the distance to the page 
bottom. 


A macro-invocation trap effective in the current diversion may be 
planted using dt. The .t register works in a diversion; if there is no 
subsequent trap a large distance is returned. For a description of 
input-line-count traps, see the it request below. 
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Request Initial If No 


Form Value Argument Explanation & Notes* 
.de xx yy - Lyy=.. Define or redefine the macro xx. The con- 


tents of the macro begin on the next input 
line. Input lines are copied in copy mode 
until the definition is terminated by a line 
beginning with .yy, whereupon the macro yy 
is called. In the absence of yy, the definition 
is terminated by a line beginning with "..". 
A macro may contain de requests provided 
the terminating macros differ or the con- 
tained definition terminator is concealed. 
*.." can be concealed as \\.. which will 
copy as \.. and be reread as "..". 


.am xx yy - y=. Append to macro (append version of de). 


«ds xx string - ignored Define a string xx containing string. Any ini- 
tial double-quote in string is stripped off to 
permit initial blanks. 


aS xx string - ignored Append string to string xx (append version of 
ds). 
.fm xx - ignored Remove request, macro, or string. The name 


xx is removed from the name list and any 
related storage space is freed. Subsequent 
references will have no effect. 


“Pn xx yy - ignored Rename request, macro, or string xx to yy. 
If yy exists, it is first removed. 


«di xx - end Divert output to macro xx. Normal text pro- 
cessing occurs during diversion except that 
page offsetting is not done. The diversion 
ends when the request di or da is encountered 
without an argument; extraneous requests of 
this type should not appear when nested 
diversions are being used. [See Note D] 


da xx - end Divert, appending to xx (append version of 
di). [See Note D] 


* Notes are explained at the end of the Summary above. 
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owh N xx - - Install a trap to invoke xx at page position N; 
a negative N will be interpreted with respect 
to the page bottom. Any macro previously 
planted at N is replaced by xx. A zeroN 
refers to the top of a page. In the absence of 
xx, the first found trap at N, if any, is 
removed. [See Note v] 


ch xx N - - Change the trap position for macro xx to be 
N. In the absence of N, the trap, if any, is 
removed. [See Note v] 


dt N xx - off Install a diversion trap at position N in the 
current diversion to invoke macro xx. 
Another dt will redefine the diversion trap. 
If no arguments are given, the diversion trap 
is removed. [See Notes D,v] 


it N xx - off Set an input-line-count trap to invoke the 
macro xx after N lines of text input have been 
read (control or request lines don’t count). 
The text may be in-line text or text interpo- 
lated by inline or trap-invoked macros. [See 
Note E] 

em xx none none The macro xx will be invoked when all input 
has ended. The effect is the same as if the 
contents of xx had been at the end of the last 
file processed. 


8. Number Registers 


A variety of parameters are available to the user as predefined, 
named number registers (see Summary). In addition, the user may 
define his own named registers. Register names are one or two char- 
acters long and do not conflict with request, macro, or string names. 
Except for certain predefined read-only registers, a number register 
can be read, written, automatically incremented or decremented, and 
interpolated into the input in a variety of formats. One common use 
of user-defined registers is to automatically number sections, para- 
graphs, lines, etc. A number register may be used any time numeri- 
cal input is expected or desired and may be used in numerical expres- 
sions ($1.4). 


Number registers are created and modified using nr, which specifies 
the name, numerical value, and the auto-increment size. Registers 
are also modified, if accessed with an auto-incrementing sequence. If 
the registers x and xx both contain N and have the auto-increment size 
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M, the following access sequences have the effect shown: 


Effect on Value 
| Sequence | — Register Interpolated 

\nx none N 
\n(wx none N 
\nt+x x incremented by M@ N+M 
\n-x x decremented by M N-M 
\n+(xx xx incremented by M N+M 
\n—(xx xx decremented by M N-M 


When interpolated, a number register is converted to decimal 
(default), decimal with leading zeros, lower-case Roman, upper-case 
Roman, lower-case sequential alphabetic, or upper-case sequential 
alphabetic according to the format specified by af. 


Request Initial If No 

Form Value Argument Explanation & Notes* 

mrR+tNM— - - The number register R is assigned the 
value +N with respect to the previous 
value, if any. The increment for auto- 
incrementing is set to M. [See Note u] 

eaf Rc arabic - Assign format c to register R. The avail- 


* 


able formats are: 


Numbering 
Format Sequence 
1 0,1,2,3,4,5,... 
001 000,001 ,002 ,003 ,004,005,... 
i 0,i, ii,iii,iv,v,... 
I 0,1,0,TH,IV,V,... 
a 0,a,b,c,...,Z,aa,ab,...,zz,aaa,... 
A 0,A,B,C,...,Z, AA,AB,...,ZZ,AAA,... 


An arabic format having N digits speci- 
fies a field width of N digits (example 2 
above). The read-only registers and the 
width function ($11.2) are always arabic. 


Notes are explained at the end of the Summary above. 
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rR - ignored Remove register R. If many registers are 
being created dynamically, it may 
become necessary to remove no longer 
used registers to recapture internal 
storage space for newer registers. 


9. Tabs, Leaders and Fields 


9.1 Tabs and Leaders 


The ASCII horizontal tab character and the ASCII SOH (hereafter 
known as the leader character) can both be used to generate either 
horizontal motion or a string of repeated characters. The length of 
the generated entity is governed by internal tab stops specifiable with 
ta. The default difference is that tabs generate motion and leaders 
generate a string of periods; te and le offer the choice of repeated 
character or motion. There are three types of internal tab stops—left 
adjusting, right adjusting, and centering. In the following table: D is 
the distance from the current position on the input line (where a tab 
or leader was found) to the next tab stop; next-string consists of the 
input characters following the tab (or leader) up to the next tab (or 
leader) or end of line; and W is the width of next-string. 


Tab Length of motion or Location of 
e repeated characters next-string 


Left D Following D 
Right D-W Right adjusted within D 
Centered D-W/2 Centered on right end of D 


The length of generated motion is allowed to be negative, but that of 
a repeated character string cannot be. Repeated character strings 
contain an integer number of characters, and any residual distance is 
prepended as motion. Tabs or leaders found after the last tab stop 
are ignored, but may be used as next-string terminators. 


Tabs and leaders are not interpreted in copy mode. \t and \a always 
generate a non-interpreted tab and leader respectively, and are 
equivalent to actual tabs and leaders in copy mode. 
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9.2 Fields 


A field is contained between a pair of field delimiter characters, and 
consists of sub-strings separated by padding indicator characters. The 
field length is the distance on the input line from the position where 
the field begins to the next tab stop. The difference between the total 
length of all the sub-strings and the field length is incorporated as 
horizontal padding space that is divided among the indicated padding 
places. The incorporated padding is allowed to be negative. For 
example, if the field delimiter is # and the padding indicator is ~, 
#-xxx7 right # specifies a right-adjusted string with the string xxx cen- 
tered in the remaining space. 


Request Initial If No 
Form Value Argument Explanation & Notes* 


ata Nr... 8n; none Set tab stops and types. rR, right adjusting; 
0.5in* t=C, centering; t absent, left adjusting. TROFF tab 
stops are preset every 0.Sin.; NROFF every 8 char- 
acter widths. The stop values are separated by 
spaces, and a value preceded by + is treated as an 
increment to the previous stop value. [See Notes 
E,m] 


tec none none The tab repetition character becomes c, or is 
removed specifying motion. [See Note E] 


lec : none The leader repetition character becomes c, or is 
removed specifying motion. [See Note E] 


.fe a b off off The field delimiter is set to a; the padding indica- 
tor is set to the space character or to b, if given. 
In the absence of arguments the field mechanism 
is turned off. 


* Notes are explained at the end of the Summary above. 


Values separated by ";" are for NROFF and TROFF respectively. 
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10. Input and Output Conventions and Char- 
acter Translations 


10.1 Input Character Translations 


Ways of inputting the graphic character set were discussed in §2.1. 
The ASCII control characters horizontal tab (§9.1), SOH (§9.1), and 
backspace (§10.3) are discussed elsewhere. The newline delimits 
input lines. In addition, STX, ETX, ENQ, ACK, and BEL are 
accepted, and may be used as delimiters or translated into a graphic 
with tr (§10.5). AJl others are ignored. 


The escape character \ introduces escape sequences—causes the fol- 
lowing character to mean another character, or to indicate some func- 
tion. A complete list of such sequences is given in the Summary. \ 
should not be confused with the ASCII control character ESC of the 
same name. The escape character \ can be input with the sequence 
\\. The escape character can be changed with ec, and all that has 
been said about the default \ becomes true for the new escape char- 
acter. \e can be used to print whatever the current escape character 
is. If necessary or convenient, the escape mechanism may be turned 
off with eo, and restored with ec. 


Request Initial If No 
Form Value Argument Explanation & Notes* 


ec \ \ Set escape character to \, or to c, if given. 


eo on - Turn escape mechanism off. 


10.2 Ligatures 


Five ligatures are available in the current TROFF character set —- fi, 
fl, ff, fi, and fl. They may be input (even in NROFF) by \(fi, \(fl, 
\(ff, \(Fi, and \(FI respectively. The ligature mode is normally on 
in TROFF, and automatically invokes ligatures during input. 


* Notes are explained at the end of the Summary above. 
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Request Initial If No 
Form Value Argument Explanation & Notes* 


gn off; on on Ligature mode is turned on if N is absent 
or non-zero, and turned off if N=0. If 
N=2, only the two-character ligatures are 
automatically invoked. Ligature mode is 
inhibited for request, macro, string, 
register, or file names, and in copy mode. 
No effect in NROFF. 


10.3 Backspacing, Underlining, Overstriking, Etc. 


Unless in copy mode, the ASCII backspace character is replaced by a 
backward horizontal motion having the width of the space character. 
Underlining as a form of line-drawing is discussed in §12.4. A gen- 
eralized overstriking function is described in §12.1. 


NROFF automatically underlines characters in the underline font, 
specifiable with uf, normally Times Italic on font position 2 (see 
§2.2). In addition to ft and \fF, the underline font may be selected 
by ul and cu. Underlining is restricted to an output-device-dependent 
subset of reasonable characters. 


Request Initial If No 
Form Value Argument Explanation & Notes* 


.cuN off N=1 A variant of ul that causes every charac- 
ter to be underlined in NROFF. Identical 
to ul in TROFF. [See Note E] 


.uf F Italic Italic Underline font set to F. In NROFF, F 
may not be on position 1 (initially Times 
Roman). 


* 


Notes are explained at the end of the Summary above. 
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sul N off N=1 Underline in NROFF (italicize in TROFF) 
the next N input text lines. Actually, 
switch to underline font, saving the 
current font for later restoration; other 
font changes within the span of a ul will 
take effect, but the restoration will undo 
the last change. Output generated by tl 
($14) is affected by the font change, but 
does not decrement N. If N>1, there is 
the risk that a trap interpolated macro 
may provide text lines within the span; 
environment switching can prevent this. 
[See Note E] 


10.4 Control Characters 


- 


Both the control character . and the no-break control character “ may 
be changed, if desired. Such a change must be compatible with the 
design of any macros used in the span of the change, and particularly 
of any trap-invoked macros. 


Request Initial If No 


Form Value Argument Explanation & Notes* 
cc C ; : The basic control character is set to c, or 


reset to ".". [See Note E] 


.c2c 7 % The nobreak control character is set to c, 
or reset to "~". [See Note EF] 


10.5 Output Translation 


One character can be made a stand-in for another character using tr. 
All text processing (e. g. character comparisons) takes place with the 
input (stand-in) character which appears to have the width of the 
final character. The graphic translation occurs at the moment of out- 
put (including diversion). 


* 


Notes are explained at the end of the Summary above. 
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Request Initial If No 


Form Value Argument Explanation & Notes* 
tr abcd.... none - Translate a into b, c into d, etc. If an 


odd number of characters is given, the 
last one will be mapped into the space 
character. To be consistent, a particular 
translation must stay in effect from input 
to output time. [See Note O] 


10.6 Transparent Throughput 


An input line beginning with a \! is read in copy mode and tran- 
sparently output (without the initial \!); the text processor is other- 
wise unaware of the line’s presence. This mechanism may be used to 
pass control information to a post-processor or to imbed control lines 
in a macro created by a diversion. 


10.7 Comments and Concealed Newlines 


An uncomfortably long input line that must stay one line (e. g. a 
string definition, or nofilled text) can be split into many physical lines 
by ending all but the last one with the escape \. The sequence 
\(newline) is a/ways ignored—except in a comment. Comments may 
be imbedded at the end of any line by prefacing them with \". The 
newline at the end of a comment cannot be concealed. A line begin- 
ning with \" will appear as a blank line and behave like .sp 1; a com- 
ment can be on a line by itself by beginning the line with .\". 


11. Local Horizontal and Vertical Motions and 
the Width Function 


11.1 Local Motions 


The functions \v“N “ and \h“N * can be used for local vertical and 
horizontal motion respectively. The distance N may be negative; the 
positive directions are rightward and downward. A local motion is 
one contained within a line. To avoid unexpected vertical 


* Notes are explained at the end of the Summary above. 
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dislocations, it is necessary that the net vertical local motion within a 
word in filled text and otherwise within a line balance to zero. The 
above and certain other escape sequences providing local motion are 
summarized in the following tables. 


Vertical Effect in 
Local Motion TROFF NROFF 
|L— \viN ~ Move distance N 
\u % em up % line up 
\d % em down | % line down 
\r 1 em up 1 line up 
Horizontal Effect in 
Local Motion TROFF NROFF 


Move distance N 
Unpaddable space-size space 
Digit-size space 


1/6 em space 
1/12 em space 


As an example, E* could be generated by the sequence 
E\s—2\v “0.4m °2\v “0.4m °\s+2; it should be noted in this exam- 
ple that the 0.4 em vertical motions are at the smaller size. 


ignored 
ignored 


11.2 Width Function 


The width function \wstring ~ generates the numerical width of 
string (in basic units). Size and font changes may be safely imbedded 
in string, and will not affect the current environment. For example, 
.ti-\w1. “u could be used to temporarily indent leftward a distance 
equal to the size of the string "I. ". 


The width function also sets three number registers. The registers st 
and sb are set respectively to the highest and lowest extent of string 
relative to the baseline; then, for example, the total height of the 
string is \n(stu-\n(sbu. In TROFF the number register ct is set to a 
value between 0 and 3: 0 means that all of the characters in string 
were short lower case characters without descenders (like e); 1 means 
that at least one character has a descender (like y); 2 means that at 
least one character is tall (like H); and 3 means that both tall charac- 
ters and characters with descenders are present. 
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11.3. Mark Horizontal Place 


The escape sequence \kx will cause the current horizontal position in 
the input line to be stored in register x. As an example, the construc- 
tion \kxword\h~ | \nxu+2u “word will embolden word by backing 
up to almost its beginning and overprinting it, resulting in word. 


12. Overstrike, Bracket, Line-Drawing and 
Zero-Width Functions 


12.1 Overstriking 


Automatically centered overstriking of up to nine characters is pro- 
vided by the overstrike function \o “string “. The characters in string 
are overprinted with centers aligned; the total width is that of the 
widest character. string should not contain local vertical motion. As 
examples, \o“e\ ~~ produces €, and \o“\(mo\(sl° produces €. 


12.2 Zero-width Characters 


The function \zc will output c without spacing over it, and can be 
used to produce left-aligned overstruck combinations. As examples, 
\z\(ci\(pl will produce ®, and \(br\z\(rn\(ul\(br will produce the 
smallest possible constructed box (J. 


12.3 Large Brackets 


The Special Mathematical Font contains a number of bracket con- 
struction pieces ( ( |) J { $ | L J] []) that can be combined into 
various bracket styles. The function \b “string ~ may be used to pile 
up vertically the characters in string (the first character on top and the 
last at the bottom); the characters are vertically separated by 1 em 
and the total pile is centered 1/2 em above the current baseline (% line 
in NROFF). For example, 


\b~* \(de\df “EX | \b* \(re\ (rf ~ \x* 0.5m ° \x *0.5m ° 
produces [E]. 
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12.4 Line Drawing 


The function \1 “Nc ~ will draw a string of repeated c’s towards the 
right for a distance N. (\f is \(lower case L). If c looks like a con- 
tinuation of an expression for N, it may insulated from N with a \&. 
If c is not specified, the _ (baseline rule) is used (underline character 
in NROFF). If N is negative, a backward horizontal motion of size N 
is made before drawing the string. Any space resulting from N/(size 
of c) having a remainder is put at the beginning (left end) of the 
string. In the case of characters that are designed to be connected 
such as baseline-rule _, underrule _, and root-en , the remainder 
space is covered by over-lapping. If N is less than the width of c, a 
single c is centered on a distance N. As an example, a macro to 
underscore a string can be written 


.de ul 
\NS$IN TE | ONC’ 


or one to draw a box around a string 


.de bx 
\(br\ | \\SIN\ | \(br\ 1 * | O\Gen\ 1% 1 O\CuT~ 


such that 
.ul "underlined words" 
and 


-bx "words in a box" 
yield underlined words and 


The function \L° Nc ~ will draw a vertical line consisting of the 
(optional) character c stacked vertically apart 1 em (1 line in NROFF), 
with the first two characters overlapped, if necessary, to form a con- 
tinuous line. The default character is the box rule ||| (\(br); the 
other suitable character is the bold vertical | (\(bv). The line is 
begun without any initial motion relative to the current base line. A 
positive N specifies a line drawn downward and a negative N specifies 
a line drawn upward. After the line is drawn no compensating 
motions are made; the instantaneous baseline is at the end of the line. 
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The horizontal and vertical line drawing functions may be used in 
combination to produce large boxes. The zero-width box-rule and the 
%-em wide underrule were designed to form corners when using 1-em 
vertical spacings. For example the macro 


.de eb 
.sp-1  \"compensate for next automatic base-line spacing 
anf \"avoid possibly overflowing word buffer 


\"next line draws box 
\he-.5n°\L* \\nau-1°\l7 \\nGlu¢ in\(ul\L7- \\nauti“\l* Ou-.5n\(al’ 
fi 


will draw a box around some text whose beginning vertical place was 
saved in number register a (e. g. using .mk a) as done for this para- 
Lgraph, 


13. Hyphenation 


The automatic hyphenation may be switched off and on. When 
switched on with hy, several variants may be set. A hyphenation indi- 
cator character may be imbedded in a word to specify desired hyphe- 
nation points, or may be prepended to suppress hyphenation. In 
addition, the user may specify a small exception word list. 


Only words that consist of a central alphabetic string surrounded by 
(usually null) non-alphabetic strings are considered candidates for 
automatic hyphenation. Words that were input containing hyphens 
(minus), em-dashes (\(em), or hyphenation indicator characters— 
such as mother-in-law—are always subject to splitting after those 
characters, whether or not automatic hyphenation is on or off. 


Request Initial If No 

Form Value Argument Explanation & Notes* 

-nh hyphen- - Automatic hyphenation is turned off. [See 
ate Note E] 


* Notes are explained at the end of the Summary above. 
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shyN on, N=1 on,N=1 Automatic hyphenation is turned on for 
N=1, or off for N=0. If N=2, last lines 
(ones that will cause a trap) are not 
hyphenated. For N=4 and 8, the last and 
first two characters respectively of a word are 
not split off. These values are additive; i. e. 
N= 14 will invoke all three restrictions. [See 
Note E] 


«he c \% \% Hyphenation indicator character is set to c or 
to the default \%. The indicator does not 
appear in the output. [See Note E] 


chw word]... - ignored Specify hyphenation points in words with 
imbedded minus signs. Versions of a word 
with terminal s are implied; i. e. dig—it 
implies dig—its. This list is examined initially 
and after each suffix stripping. The space 
available is small—about 128 characters. 


14. Three Part Titles 


The titling function tl provides for automatic placement of three fields 
at the left, center, and right of a line with a title-length specifiable 
with It. tl may be used anywhere, and is independent of the normal 


text collecting process. A common use is in header and footer mac- 
ros. 


Request Initial If No 

Form Value Argument __ Explanation & Notes* 

“pe c % off The page number character is set 
to c, or removed. The page- 
number register remains %. 

Alt +N 6.5 in previous Length of title set to +N. The 


line-length and the title-length 
are independent. Indents do not 
apply to titles; page-offsets do. 
[See Notes E,m] 


* Notes are explained at the end of the Summary above. 
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tl “left “center “right ° - The strings left, center, and right 
are respectively left-adjusted, 
centered, and right-adjusted in 
the current title-length. Any of 
the strings may be empty, and 
overlapping is permitted. If the 
page-number character (initially 
%) is found within any of the 
fields it is replaced by the 
current page number having the 
format assigned to register %. 
Any character may be used as 
the string delimiter. 


15. Output Line Numbering 


Automatic sequence numbering of output lines may be requested 
with nm. When in effect, a three-digit, arabic number plus a 
3 digit-space is prepended to output text lines. The text lines are 
thus offset by four digit-spaces, and otherwise retain their line 
length; a reduction in line length may be desired to keep the 
6 right margin aligned with an earlier margin. Blank lines, other 
vertical spaces, and lines generated by tl are not numbered. 
Numbering can be temporarily suspended with nn, or with an 
9 .nm followed by a later .nm +0. In addition, a line number 
indent /, and the number-text separation S may be specified in 
digit-spaces. Further, it can be specified that only those line 
12 numbers that are multiples of some number M are to be printed 
(the others will appear as blank number fields). 


Request Initial If No 
Form Value Argument Explanation & Notes* 
.nn N - N=1 The next N text output lines are not 


numbered. [See Note E] 


* Notes are explained at the end of the Summary above. 
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Line number mode. If +N is given, 
line numbering is turned on, and the 
next output line numbered is num- 
bered +N. Default values are M=1, 
S=1, and /=0. Parameters 
corresponding to missing arguments 
are unaffected; a non-numeric argu- 
ment is considered missing. In the 
absence of all arguments, numbering 
is turned off; the next line number is 
preserved for possible further use in 
number register In. [See Note E] 


As an example, the paragraph portions of this section are num- 

15 bered with M=3: .nm 1 3 was placed at the beginning; .nm was 
placed at the end of the first paragraph; and .nm +0 was placed 
in front of this paragraph; and .nm finally placed at the end. 

18 Line lengths were also changed (by \w~0000°u) to keep the 
right side aligned. Another example is .nm +5 5 x 3 which turns 
on numbering with the line number of the next line to be 5 

21 greater than the last numbered line, with M=5, with spacing S 
untouched, and with the indent / set to 3. 


16. Conditional Acceptance of Input 


In the following, c is a one-character, built-in condition name, ! signi- 
fies not, N is a numerical expression, string] and string2 are strings 
delimited by any non-blank, non-numeric character nor in the strings, 
and anything represents what is conditionally accepted. 


Request Form 


Explanation & Notes* 


«if c anything 


If condition c true, accept anything as input; in 


multi-line case use \ {anything \}. 


wif !c anything 
.if N anything 


wif !N anything 
u] 


* 
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If condition c false, accept anything. 
If expression N > 0, accept anything. [See Note u] 


If expression N = 0, accept anything. [See Note 


Notes are explained at the end of the Summary above. 
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wif “string] *string2 ° anything If string] identical to string2, accept anything. 


.if ! “string! *string2 * anything If string] not identical to string2, accept anything. 


.ie ¢ anything If portion of if-else; all above forms (like if). [See 
Note uj 
.el anything Else portion of if-else. 


The built-in condition names are: 


Condition 
Name True If 
| 
0 Current page number is odd 
e Current page number is even 
t Formatter is TROFF 
n Formatter is NROFF 


If the condition c is true, or if the number AN is greater than zero, or 
if the strings compare identically (including motions and character 
size and font), anything is accepted as input. If a! precedes the con- 
dition, number, or string comparison, the sense of the acceptance is 
reversed, 


Any spaces between the condition and the beginning of anything are 
skipped over. The anything can be either a single input line (text, 
macro, or whatever) or a number of input lines. In the multi-line 
case, the first line must begin with a left delimiter \{ and the last 
line must end with a right delimiter \}. 


The request ie (if-else) is identical to if except that the acceptance 
state is remembered. A subsequent and matching el (else) request 
then uses the reverse sense of that state. ie - el pairs may be nested. 


Some examples are: 
.ife .t] ~“ Even Page % ° ~° 
which outputs a title if the page number is even; and 


eile \n%>1 \{\ 
*sp 0.5i 

-Ul ~“ Page %° ~*~ 
*sp | 1.21 \} 

el .sp | 2.51 


which treats page 1 differently from other pages. 
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17. Environment Switching 


A number of the parameters that control the text processing are gath- 
ered together into an environment, which can be switched by the user. 
The environment parameters are those associated with requests noting 
E in their Notes column; in addition, partially collected lines and 
words are in the environment. Everything else is global; examples are 
page-oriented parameters, diversion-oriented parameters, number 
registers, and macro and string definitions. All environments are ini- 
tialized with default parameter values. 


Request Initial If No 
Form Value Argument Explanation & Notes* 
ev N N=0 previous Environment switched to environment 


0=N=2. Switching is done in push-down 
fashion so that restoring a previous 
environment must be done with .ev rather 
than specific reference. 


18. Insertions from the Standard Input 


The input can be temporarily switched to the system standard input 
with rd, which will switch back when two newlines in a row are found 
(the extra blank line is not used). This mechanism is intended for 
insertions in form-letter-like documentation. On UNIX, the standard 
input can be the user’s keyboard, a pipe, or a file. 


Request Initial If No 
Form Value Argument Explanation & Notes* 
eX : - Exit from NROFF/TROFF. Text pro- 


cessing is terminated exactly as if all 
input had ended. 


* Notes are explained at the end of the Summary above. 
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.rd prompt - prompt=BEL Read insertion from the standard 
input until two newlines in a row are 
found. If the standard input is the 
user’s keyboard, prompt (or a BEL) is 
written onto the user’s terminal. rd 
behaves like a macro, and arguments 
may be placed after prompt. 


If insertions are to be taken from the terminal keyboard while output 
is being printed on the terminal, the command line option -q will 
turn off the echoing of keyboard input and prompt only with BEL. 
The regular input and insertion input cannor simultaneously come 
from the standard input. 


As an example, multiple copies of a form letter may be prepared by 
entering the insertions for all the copies in one file to be used as the 
standard input, and causing the file containing the letter to reinvoke 
itself using nx ($19); the process would ultimately be ended by an ex 
in the insertion file. 


19. Input/Output File Switching 


The (read-only) number register .c contains the input line number in 
the current input file. The number register c. is a general register 
serving the same purpose. 


Request Initial If No 

Form Value Argument Explanation & Notes* 

So filename - Switch source file. The top input (file 
reading) level is switched to filename. 
The effect of an so encountered in a 
macro occurs immediately. When the 
new file ends, input is again taken from 
the original file. so’s may be nested. 

nx filename - end-of-file Next file is filename. The current file is 


considered ended, and the input is 
immediately switched to filename. 


* Notes are explained at the end of the Summary above. 
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«pi program 


Pipe output to program (NROFF only). 
This request must occur before any print- 
ing occurs. No arguments are transmit- 
ted to program. 


20. Miscellaneous 


Request Initial If No 
Form Value Argument 
“mecN - off 

.tm string - newline 
«ig yy - yee 
-_pm t - all 


* 


Explanation & Notes* 


Specifies that a margin character c 
appear a distance N to the right of the 
right margin after each non-empty text 
line (except those produced by tl). If the 
output line is too-long (as can happen in 
nofill mode) the character will be 
appended to the line. If N is not given, 
the previous N is used; the initial N is 
0.2 inches in NROFF and 1 em in TROFF. 
The margin character used with this 
paragraph was a 12-point box-rule. [See 
Notes E,m] 


After skipping initial blanks, string (rest 
of the line) is read in copy mode and writ- 
ten on the user’s terminal. (see §21). 


Ignore input lines. ig behaves exactly 
like de ($7) except that the input is dis- 
carded. The input is read in copy mode, 
and any auto-incremented registers will 
be affected. 


Print macros. The names and sizes of all 
of the defined macros and strings are 
printed on the user’s terminal; if ¢ is 
given, only the total of the sizes is 
printed. The sizes is given in blocks of 
128 characters. 


Notes are explained at the end of the Summary above. 
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.ab string - - Print string on standard error and ter- 
minate immediately. The default string is 
"User Abort". Does not cause a break. 
Only output preceding the last break is 
written. 


fl - - Flush output buffer. Used in interactive 
debugging to force output. 


21. Output and Error Messages 


The output from tm, pm, ab and the prompt from rd, as well as vari- 
ous error messages are written onto UNIX’s standard error output. 
The latter is different from the standard output, where NROFF format- 
ted output goes. By default, both are written onto the user’s termi- 
nal, but they can be independently redirected. 


Various error conditions may occur during the operation of NROFF 
and TROFF. Certain less serious errors having only local impact do 
not cause processing to terminate. Two examples are word overflow, 
caused by a word that is too large to fit into the word buffer (in fill 
mode), and line overflow, caused by an output line that grew too large 
to fit in the line buffer; in both cases, a message is printed, the 
offending excess is discarded, and the affected word or line is marked 
at the point of truncation with a * in NROFF and a win TROFF. The 
philosophy is to continue processing, if possible, on the grounds that 
output useful for debugging may be produced. If a serious error 
occurs, processing terminates, and an appropriate message is printed. 
Examples are the inability to create, read, or write files, and the 
exceeding of certain internal limits that make future output unlikely 
to be useful. 


Tutorial Examples 


T1. Introduction 


Although NROFF and TROFF have by design a syntax reminiscent of 
earlier text processors* with the intent of easing their use, it is almost 
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always necessary to prepare at least a small set of macro definitions to 
describe most documents. Such common formatting needs as page 
margins and footnotes are deliberately not built into NROFF and 
TROFF. Instead, the macro and string definition, number register, 
diversion, environment switching, page-position trap, and conditional 
input mechanisms provide the basis for user-defined implementations. 


The examples to be discussed are intended to be useful and somewhat 
realistic, but won’t necessarily cover all relevant contingencies. Expli- 
cit numerical parameters are used in the examples to make them 
easier to read and to illustrate typical values. In many cases, number 
registers would really be used to reduce the number of places where 
numerical information is kept, and to concentrate conditional param- 
eter initialization like that which depends on whether TROFF or 
NROFF is being used. 


T2. Page Margins 


As discussed in §3, header and footer macros are usually defined to 
describe the top and bottom page margin areas respectively. A trap is 
planted at page position 0 for the header, and at —N (N from the page 
bottom) for the footer. The simplest such definitions might be 


.de hd \ "define header 
’sp li 

a \"end definition 
.de fo \ "define footer 
*bp 

“s \"end definition 
-wh 0 hd 

.wh —-1i fo 


which provide blank 1 inch top and bottom margins. The header will 
occur on the first page, only if the definition and trap exist prior to 
the initial pseudo-page transition (§3). In fill mode, the output line 
that springs the footer trap was typically forced out because some part 
or whole word didn’t fit on it. If anything in the footer and header 


* 


For example: P. A. Crisman, Ed., The Compatible Time-Sharing System, MIT 
Press, 1965, Section AH9.01 (Description of RUNOFF program on MIT's 
CTSS system). 
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that follows causes a break, that word or part word will be forced out. 
In this and other examples, requests like bp and sp that normally 
cause breaks are invoked using the no-break control character ~ to 
avoid this. When the header/footer design contains material requir- 
ing independent text processing, the environment may be switched, 
avoiding most interaction with the running text. 


A more realistic example would be 


.de hd \ "header 

Jif t tl ~ \Qrn’ ~\(rn~ \"troff cut mark 

Jif \\n%>1 \{\ 

*sp 0.5i-1 \"tl base at 0.5i 

wth ~“- % -"* \"centered page number 
.ps \ "restore size 

ft \"restore font 

evs \} \"restore vs 

’sp 1.0i \"space to 1.0i 

ns \"turn on no-space mode 
.de fo \ "footer 

-ps 10 \"set footer/header size 
ft R \"set font 

.vs 12p \"set base-line spacing 
Jif \\n%=1 \{\ 

*sp. \\n(.pu-0.5i-1 \"tl base 0.5i up 

th ~“- % -"~ \} \ "first page number 
*bp 

.wh 0 hd 

-wh —li fo 


which sets the size, font, and base-line spacing for the header/footer 
material, and ultimately restores them. The material in this case is a 
page number at the bottom of the first page and at the top of the 
remaining pages. If TROFF is used, a cut mark is drawn in the form 
of root-en’s at each margin. The sp’s refer to absolute positions to 
avoid dependence on the base-line spacing. Another reason for this 
in the footer is that the footer is invoked by printing a line whose 
vertical spacing swept past the trap position by possibly as much as 
the base-line spacing. The no-space mode is turned on at the end of 
hd to render ineffective accidental occurrences of sp at the top of the 
running text. 


The above method of restoring size, font, etc. presupposes that such 
requests (that set previous value) are nor used in the running text. A 
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better scheme is save and restore both the current and previous values 
as shown for size in the following: 


.de fo 

-nrsi \\n(s  \"current size 

.ps 

.nr s2 \\n(.s \" previous size 

oo \"rest of footer 

.de hd 

.on \"header stuff 

-ps \\n(s2 \"restore previous size 


-ps \\n(s1 \ "restore current size 


Page numbers may be printed in the bottom margin by a separate 
macro triggered during the footer’s page ejection: 


.de bn \"bottom number 
th ~“-%-"~" \"centered page number 


.wh -0.5i-lv bn \"tl base 0.51 up 


T3. Paragraphs and Headings 


The housekeeping associated with starting a new paragraph should be 
collected in a paragraph macro that, for example, does the desired 
preparagraph spacing, forces the correct font, size, base-line spacing, 
and indent, checks that enough space remains for more than one line, 
and requests a temporary indent. 


.de pg \" paragraph 

-br \" break 

ft R \ "force font, 

-ps 10 \ "size, 

-vs 12p \ "spacing, 

.in 0 \"and indent 

sp 0.4 \" prespace 

ene 1+\\n(.Vu \"want more than 1 line 


.ti 0.21 \"temp indent 


The first break in pg will force out any previous partial lines, and 
must occur before the vs. The forcing of font, etc. is partly a defense 
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against prior error and partly to permit things like section heading 
macros to set parameters only once. The prespacing parameter is 
suitable for TROFF; a larger space, at least as big as the output device 
vertical resolution, would be more suitable in NROFF. The choice of 
remaining space to test for in the ne is the smallest amount greater 
than one line (the .V is the available vertical resolution). 


A macro to automatically number section headings might look like: 


.de sc \" section 

wo \"force font, etc. 
sp 0.4 \" prespace 

ene 2.4+\\n(.Vu \" want 2.4+ lines 
fi 

\\n+sS. 

nrS01 \"init S 


The usage is .sc, followed by the section heading text, followed by 
.pg. The ne test value includes one line of heading, 0.4 line in the 
following pg, and one line of the paragraph text. A word consisting 
of the next section number and a period is produced to begin the 
heading line. The format of the number may be set by af (§8). 


Another common form is the labeled, indented paragraph, where the 
label protrudes left into the indent space. 


.de Ip \"labeled paragraph 
“Pg 

cin 0.5% \" paragraph indent 
.ta 0.2: 0.5i \"label, paragraph 

.ti 0 

\t\\$IAt\c \"flow into paragraph 


The intended usage is ".Ip label"; label will begin at 0.2inch, and 
cannot exceed a length of 0.3inch without intruding into the para- 
graph. The label could be right adjusted against 0.4inch by setting 
the tabs instead with .ta 0.4iR 0.5i. The last line of Ip ends with \c 
so that it will become a part of the first line of the text that follows. 
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T4. Multiple Column Output 


The production of multiple column pages requires the footer macro to 
decide whether it was invoked by other than the last column, so that 
it will begin a new column rather than produce the bottom margin. 
The header can initialize a column register that the footer will incre- 
ment and test. The following is arranged for two columns, but is 
easily modified for more. 


.de hd \ "header 

-nr cl 01 \ "init column count 
«mk \"mark top of text 
.de fo \" footer 

vie \\n+(cl<2 \{\ 

.po +3.4i \"next column; 3.1+0.3 
rt \"back to mark 

ons \} \"no-space mode 

cel \(\ 

-po \\nMu \“restore left margin 
*bp \} 

wl 3.11 \"column width 

.nr M \\n(.o \"save left margin 


Typically a portion of the top of the first page contains full width 
text; the request for the narrower line length, as well as another .mk 
would be made where the two column output was to begin. 


T5. Footnote Processing 


The footnote mechanism to be described is used by imbedding the 
footnotes in the input text at the point of reference, demarcated by an 
initial .fn and a terminal .-ef: 


fn 
Footnote text and control lines... 
ef 


In the following, footnotes are processed in a separate environment 
and diverted for later printing in the space immediately prior to the 
bottom margin. There is provision for the case where the last 
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collected footnote doesn’t completely fit in the available space. 


.de hd 
mrx01 

.nr y 0\\nb 
.ch fo —\\nbu 
if \\n(dn .fz 


.de fo 

-nr dn 0 

Jif \\nx \t\ 

.ev 1 

nf 

«FN 

.rm FN 

Af "\\nGz"fy" .di 
-nr x 0 

.ev \} 


*bp 


.de fx 

-if \\nx .di fy 
.de fn 

.da FN 

.ev 1 

«if \\n+x=1 .fs 
fi 

.de ef 

-br 

-nr z \\n(.v 
.eV 

di 

-nr y —\\n(dn 


\ "header 


\"init footnote count 
\"current footer place 
\ "reset footer trap 

\ "leftover footnote 


\" footer 
\"zero last diversion size 


\" expand footnotes in ev1 
\"retain vertical size 

\" footnotes 

\ "delete it 

\"end overflow diversion 
\ "disable fx 

\" pop environment 


\" process footnote overflow 
\ "divert overflow 


\"start footnote 

\"divert (append) footnote 
\"in environment 1 

\ "if first, include separator 
\ "fill mode 


\"end footnote 
\"finish output 
\"save spacing 

\"pop ev 

\"end diversion 
\"new footer position, 


-if \\nx=1 .nr y -(\\n(.v-\\nz) \ 


.ch fo \\nyu 


\"uncertainty correction 
\"y is negative 


if (\\n(il+1vy)>(\\n(p+\\ny) \ 


.ch fo \\n(nlut+ly 
.de fs 
\l- 1i’ 


\"it didn’t fit 


\" separator 
\"1 inch rule 
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-br 


.de fz \" get leftover footnote 


.fn 

nf \"retain vertical size 

fy \"where fx put it 

.ef 

nr b 1.0i \"bottom margin size 

.wh 0 hd \"header trap 

.wh 12i fo \"footer trap, temp position 
-wh —\\nbu fx \ "fx at footer position 

.ch fo —\\nbu \" conceal fx with fo 


The header hd initializes a footnote count register x, and sets both 
the current footer trap position register y and the footer trap itself to 
a nominal position specified in register b. In addition, if the register 
dn indicates a leftover footnote, fz is invoked to reprocess it. The 
footnote start macro fn begins a diversion (append) in environment 1, 
and increments the count x; if the count is one, the footnote separator 
fs is interpolated. The separator is kept in a separate macro to permit 
user redefinition. The footnote end macro ef restores the previous 
environment and ends the diversion after saving the spacing size in 
register z. y is then decremented by the size of the footnote, avail- 
able in dn; then on the first footnote, y is further decremented by the 
difference in vertical base-line spacings of the two environments, to 
prevent the late triggering the footer trap from causing the last line of 
the combined footnotes to overflow. The footer trap is then set to 
the lower (on the page) of y or the current page position (nl) plus one 
line, to allow for printing the reference line. If indicated by x, the 
footer fo rereads the footnotes from FN in nofill mode n environment 
1, and deletes FN. If the footnotes were too large to fit, the macro 
fx will be trap-invoked to redivert the overflow into fy, and the regis- 
ter dn will later indicate to the header whether fy is empty. Both fo 
and fx are planted in the nominal footer trap position in an order that 
causes fx to be concealed unless the fo trap is moved. The footer 
then terminates the overflow diversion, if necessary, and zeros x to 
disable fx, because the uncertainty correction together with a not- 
too-late triggering of the footer can result in the footnote rereading 
finishing before reaching the fx trap. 


A good exercise for the student is to combine the multiple-column 
and footnote mechanisms. 
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T6. The Last Page 


After the last input file has ended, NROFF and TROFF invoke the end 
macro (§7), if any, and when it finishes, eject the remainder of the 
page. During the eject, any traps encountered are processed nor- 
mally. At the end of this last page, processing terminates unless a 
partial line, word, or partial word remains. If it is desired that 
another page be started, the end-macro 


.de en \"end-macro 
\c 

*bp 

.em en 


will deposit a null partial word, and effect another last page. 
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Table I 


Font Style Examples 


The following fonts are printed in 12-point, with a vertical spacing of 
14-point, and with non-alphanumeric characters separated by 4%em 
space (all measurements on 8.5 X 11 inch paper prior to photoreduc- 
tion). This font sample is printed on an Imagen Printer, using the 
Image Network Computer Modern fonts. These fonts are similar to 
the Times fonts which were used in the original implementations of 
troff. 


Computer Modern Roman 


abcdefghijklmnopqrstuvwxyz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


1234567890 
1$% &()O*+—.,fr;=7 II | 
eOo-—--_%%*x“ A AAMT’ ¢g ®O 


Computer Modern Italic 


abcdefghtjklmnopgqrstuvwryz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
1284567890 

3%B()C*+-.,/:; meer 

eB >< UEMAAL Hi pe? tT’ ¢ eo 


Computer Modern Bold 


abcdefghijklmnopaqrstuvwxyz 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


1234567890 
1$%&()O FE. /rp= Pl] | 
eo -_ 4 euARAR mM? tf’ ¢ @o 


Special Mathematical Font 


"Vf <>{}#&+—-=* 
aBySeCnOcxkApvéotpastvdyba 
TAOAEITYOVO 

SB~e=Foethx> +t+UNCDICDLI 
SetamO@lOrOIi till fl! 
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Table II 


Input Naming Conventions for “, ~, and — 
and for Non-ASCII Special Characters 


Non-ASCII characters and minus on the standard fonts. 


Input Character Input Character 
Char Name Name Char Name Name 
aS close quote fi \(fi fi 
aa open quote fi \(fl fl 
— \(em 3/4 Em dash ff \(ff ff 
- = hyphen or fi \(Fi ffi 
-  \(hy hyphen fa = \(FI ffl 
—- \= current font minus ° ~\(de_ degree 
@ \(bu_ bullet t \(dg dagger 
O \(sq_ square ‘ —\(fm_ foot mark 
~ \(tu_ rule ¢ \(ct cent sign 
%’ \(14 1/4 ® \(rg_ registered 
% \(12 12 © \(co copyright 
% \(34 3/4 
Non-ASCII characters and “, ~, _, +, —, =, and * on the 


special font. 


The ASCII characters & #,", “, *, <, >, \, {, }, 7, *, and _ exist 
only on the special font and are printed as a 1-em space if that font is 
not mounted. The following characters exist only on the special font 
except for the upper case Greek letter names followed by ¢ which are 
mapped into upper case English letters in whatever font is mounted 
on font position one (default Times Roman). The special math plus, 
minus, and equals are provided to insulate the appearance of equa- 
tions from the choice of standard fonts. 


Input Character Input Character 

Char Name Name Char Name Name 

+  \(pl math plus a \(*a alpha 

—  \(mi math minus B \(*b_ beta 

= \(eq math equals y \(*g gamma 

*  \(** math star & \(*d delta 

§ \(sc_ section e \(*e. epsilon 

* \(aa_ acute accent € \(*z zeta 

~  \(ga_ grave accent n \(*y eta 

— \(ul underrule 6 \(*h_ theta 

/  \ (sl slash (matching backslash) t \(Ci iota 
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Char 


ILD €KEOKHMUOOMAZZSHAHOUNMPAWPESCX ESC ANADAOMCE 


IA WV 


Input Character 
Name Name 
\(*k kappa 
\C@L lambda 
\(*m mu 

\(*¥n nu 

\(fc xi 

\(*o omicron 
\Cp pi 

\(*r rho 

\(*s_ sigma 
\(ts 
\(ft tau 

\C@u_ upsilon 
\Cf phi 

\(*x chi 

\(*q_ psi 
\(fw omega 
\(7A Alphat 
\CB Betat 
\(*G Gamma 
\(*D Delta 
\CE_ Epsilont 
\(*Z Zetat 
\(*Y Etat 
\(*H_ Theta 
\CI Iotat 
\(*K. Kappat 
\(*L_ Lambda 
\(*M Mut 
\(N Nut 
\G@C Xi 

\(*O Omicront 
\CP Pi 

\(*R Rhot 
\C@S Sigma 
\(@T Taut 
\(*U_ Upsilon 
\(*F Phi 
\(*X Chit 
\(FQ Psi 
\(}W Omega 
\(sr 
\(rn 
\C= >= 
\(<= <= 


terminal sigma 


square root 
root en extender 


Ril 


l 


Od he —nQRryu: do gIUINUNDChH +x-+--+t bt 


aoe en wns" ern O = 


— 
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Input 


Char Name 


Character 
Name 


identically equal 

approx = 

approximates 

not equal 

right arrow 

left arrow 

up arrow 

down arrow 

multiply 

divide 

plus-minus 

cup (union) 

cap (intersection) 

subset of 

superset of 

improper subset 

improper superset 

infinity 

partial derivative 

gradient 

not 

integral sign 

proportional to 

empty set 

member of 

box vertical rule 

double dagger 

right hand 

left hand 

Bell System logo (typesetter- 
dependent) 

or 

circle 

left top of big curly bracket 
left bottom 

right top 

right bottom 

left center of big curly bracket 
right center of big curly bracket 
bold vertical 

left floor (left bottom of big 
square bracket) 

right floor (right bottom) 
left ceiling (left top) 

right ceiling (right top) 
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A TROFF Tutorial 


Abstract 


troff is a text-formatting program for typesetting on the UNIX operat- 
ing system. This device is capable of producing high quality text; this 
paper is an example of troff output. 


The phototypesetter itself normally runs with four fonts, containing 
roman, italic and bold letters a full greek alphabet, and a substantial 
number of special characters and mathematical symbols. Characters 
can be printed in a range of sizes, and placed anywhere on the page. 


troff allows the user full control over fonts, sizes, and character posi- 
tions, well as the usual features of a formatter—as right-margin justif- 
ication, automatic hyphenation, page titling and numbering, and so 
on. It also provides macros, arithmetic variables and operations, and 
conditional testing, for complicated formatting tasks. 


This document is an introduction to the most basic use of troff. It 
presents just enough information to enable the user to do simple for- 
matting tasks like making viewgraphs, and to make incremental 
changes to existing packages of troff commands. In most respects, the 
UNIX formatter nroff and a more recent version (device-independent 
troff) are identical to the version described here, so this document also 
serves as a tutorial for them as well. 


Source: Brian W. Kernighan (updated for 4.3BSD by Mark Seiden), A TROFF 
Tutorial (Murray Hill, N.J.: Bell Laboratories, 1978). 
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1. Introduction 


troff [1] is a text-formatting program, written originally by J. F. 
Ossanna, for producing high-quality printed output from the photo- 
typesetter on the UNIX operating system. This document is an exam- 
ple of troff output. 


The single most important rule of using troff is not to use it directly, 
but through some intermediary. In many ways, troff resembles an 
assembly language—a remarkably powerful and flexible one—but 
nonetheless such that many operations must be specified at a level of 
detail and in a form that is too hard for most people to use effec- 
tively. 


For two special applications, there are programs that provide an inter- 
face to troff for the majority of users. eqn [2] provides an easy to 
learn language for typesetting mathematics; the eqn user need know 
no troff whatsoever to typeset mathematics. tbl [3] provides the same 
convenience for producing tables of arbitrary complexity. 


For producing straight text (which may well contain mathematics or 
tables), there are a number of ‘“‘macro packages” that define format- 
ting rules and operations for specific styles of documents, and reduce 
the amount of direct contact with troff. In particular, the ‘““-ms”’ [4], 
PWB/MM [5], and ‘‘-me”’ [6] packages for internal memoranda and 
external papers provide most of the facilities needed for a wide range 
of document preparation. There are also packages for viewgraphs, 
for simulating the older roff formatters, and for other special applica- 
tions. Typically you will find these packages easier to use than troff 
once you get beyond the most trivial operations; you should always 
consider them first. 


In the few cases where existing packages don’t do the whole job, the 
solution is not to write an entirely new set of troff instructions from 


scratch, but to make small changes to adapt packages that already 
exist. 


In accordance with this philosophy of letting someone else do the 
work, the part of troff described here is only a small part of the 
whole, although it tries to concentrate on the more useful parts. In 
any case, there is no attempt to be complete. Rather, the emphasis is 
on showing how to do simple things, and how to make incremental 
changes to what already exists. The contents of the remaining sec- 
tions are: 
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2. Point sizes and line spacing 

3. Fonts and special characters 

4. Indents and line length 

5. Tabs 

6. Local motions: Drawing lines and characters 
7. Strings 

8. Introduction to macros 

9. Titles, pages and numbering 

10. Number registers and arithmetic 
11. Macros with arguments 

12. Conditionals 

13. Environments 

14. Diversions 


Appendix: Typesetter character set 


The troff described here is the C-language version supplied with UNIX 
Version 7 and 32V as documented in [1]. 


To use troff you have to prepare not only the actual text you want 
printed, but some information that tells how you want it printed. 
(Readers who use roff will find the approach familiar.) For troff the 
text and the formatting information are often intertwined quite inti- 
mately. Most commands to troff are placed on a line separate from 
the text itself, beginning with a period (one command per line). For 
example, 


Some text. 
ps 16 
Some more text. 


will change the “‘point size’, that is, the size of the letters being 
printed, to ‘16 point’ (one point is 1/72 inch) like this: 


Some text. Some more text. 
Occasionally, though, something special occurs in the middle of a 
line—to produce 

Area = mr? 


you have to type 
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Area = \(*p\fIr\fR\ \s8\u2\d\s0 


(which we will explain shortly). The backslash character 
\ is used to introduce troff commands and special characters within a 
line of text. 


2. Point Sizes; Line Spacing 


As mentioned above, the command .ps sets the point size. One point 
is 1/72 inch, so 6-point characters are at most 1/12 inch high, and 36- 
point characters are % inch. There are 15 point sizes, listed below. 

6 point: Pack my box with five dozen liquor jugs. 

7 point: Pack my box with five dozen liquor fugs. 

8 point: Pack my box with five dozen liquor jugs 

9 point: Pack my box with five dozen liquor jugs. 

10 point: Pack my box with five dozen liquor jugs. 

11 point: Pack my box with five dozen liquor jugs. 

12 point: Pack my box with five dozen liquor jugs. 


14 point: Pack my box with five dozen liquor jugs. 


16 point 18 point 20 point 


22* 24 28 36 


If the number after .ps is not one of these legal sizes, it is rounded up 
to the next valid value, with a maximum of 36. If no number follows 
ps, troff reverts to the previous size, whatever it was. troff begins 
with point size 10, which is usually fine. The original of this docu- 
ment (on 8.5 by 11 inch paper) is in 12 point. 


The point size can also be changed in the middle of a line or even a 
word with the in-line command \s. To produce 


UNIX runs on a PDP-11/45 
type 
\s8UNIX\s10 runs on a \s8PDP-\s1011/45 
As above, \s should be followed by a legal point size, except that \s0 


causes the size to revert to its previous value. Notice that \s1011 can 


* This font is not 22 points since there is no 22-point font available in the 


software used to produce this document. 
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be understood correctly as “‘size 10, followed by an 11,” if the size is 
legal, but not otherwise. Be cautious with similar constructions. 


Relative size changes are also legal and useful: 
\s-2UNIX\s+2 


temporarily decreases the size, whatever it is, by two points, then 
restores it. Relative size changes have the advantage that the size 
difference is independent of the starting size of the document. The 
amount of the relative change is restricted to a single digit. 


The other parameter that determines what the type looks like is the 
spacing between lines, which is set independently of the point size. 
Vertical spacing is measured from the bottom of one line to the bot- 
tom of the next. The command to control vertical spacing is .vs. For 
running text, it is usually best to set the vertical spacing about 20% 
bigger than the character size. For example, so far in this document, 
we have used ‘12 on 14,” that is, 


-ps 12 
vs 14p 


If we changed to 


-ps 12 
.vs 12p 


the running text would look like this. After a few lines, you will 
agree it looks a little cramped. The right vertical spacing is partly a 
matter of taste, depending on how much text you want to squeeze 
into a given space, and partly a matter of traditional printing style. 
By default, troff uses 10 on 12. 


Point size and vertical spacing make a substantial difference 
in the amount of text per square inch. This is 14 on 16. 


Point size and vertical spacing make a substantial difference in the amount of text per square inch. For example, 10 on 12 uses about twice 


as much space as 7 on 8. This is 6 on 7, which is even smaller. [t packs a lot more words per line, but you can go blind trying to read it. 


When used without arguments, .ps and .vs revert to the previous size 
and vertical spacing respectively. 


The command .sp is used to get extra vertical space. Unadorned, it 
gives you one extra blank line (one .vs, whatever that has been set 
to). Typically, that’s more or less than you want, so .sp can be fol- 
lowed by information about how much space you want— 


Sp 2i 


means ‘‘two inches of vertical space.” 
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.sp 2p 
means “‘two points of vertical space;”’ and 
sp 2 


means ‘‘two vertical spaces’’—two of whatever .vs is set to (this can 
also be made explicit with .sp 2v); troff also understands decimal frac- 
tions in most places, so 


sp 1.51 


is a space of 1.5 inches. These same scale factors can be used after 
vs to define line spacing, and in fact after most commands that deal 
with physical dimensions. 


It should be noted that all size numbers are converted internally to 
“machine units,’? which are 1/432 inch (1/6 point). For most pur- 
poses, this is enough resolution that you don’t have to worry about 
the accuracy of the representation. The situation is not quite so good 
vertically, where resolution is 1/144 inch (1/2 point). 


3. Fonts and Special Characters 


troff and the typesetter allow four different fonts at any one time. 
Normally three fonts (Times roman, italic and bold) and one collec- 
tion of special characters are permanently mounted. 


abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPORSTUVWXYZ 


abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 


The greek, mathematical symbols and miscellany of the special font 
are listed in Appendix A. 


troff prints in roman unless told otherwise. To switch into bold, use 
the .ft command 


.ftB 


and for italics, 
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ft I 


To return to roman, use .ft R; to return to the previous font, what- 
ever it was, use either .ft P or just .ft. The ‘‘underline’? command 
.ul 


causes the next input line to print in italics. .ul can be followed by a 
count to indicate that more than one line is to be italicized. 


Fonts can also be changed within a line or word with the in-line com- 
mand \f : 


boldface text 
is produced by 
\fBbold\ flIface\fR text 


If you want to do this so the previous font, whatever it was, is left 
undisturbed, insert extra \fP commands, like this: 


\fBbold\ fP\ flface\fP\fR text\fP 


Because only the immediately previous font is remembered, you have 
to restore the previous font after each change or you can lose it. The 
same is true of .ps and .vs when used without an argument. 


There are other fonts available besides the standard set, although you 
can still use only four at any given time. The command .fp tells troff 
what fonts are physically mounted on the typesetter: 


.fp 3 H 


says that the Helvetica font is mounted on position 3. (The complete 
list of font sizes and styles depends on your typesetter or laser 
printer.) Appropriate .fp commands should appear at the beginning 
of your document if you do not use the standard fonts. 


It is possible to make a document relatively independent of the actual 
fonts used to print it by using font numbers instead of names; for 
example, \f3 and .ft 3 mean “‘whatever font is mounted at position 
3,” and thus work for any setting. Normal settings are roman font 
on 1, italic on 2, bold on 3, and special on 4. 


There is also a way to get “synthetic’’ bold fonts by overstriking 
letters with a slight offset. Look at the .bd command in [1]. 


Special characters have four-character names beginning with \( , and 
they may be inserted anywhere. For example, 


A+ h=% 
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is produced by 
\(14 + \(2 = \@G4 


In particular, greek letters are all of the form \(*— , where —- is an 
upper or lower case roman letter reminiscent of the greek. Thus to 
get 


3(axp) = % 

in bare troff we have to type 
\@S(\Ca\(mu\(*b) \(— > \Gf 

That line is unscrambled as follows: 
\CS 
( 
\(*a 
\(mu 
\(*b 
) 
\(-> 
\(if 


A complete list of these special names occurs in Appendix A. 


8Stlw~wxRamnM 


In eqn [2] the same effect can be achieved with the input 
SIGMA (alpha times beta ) —> inf 
which is less concise, but clearer to the uninitiated. 


Notice that each four-character name is a single character as far as 
troff is concerned—the “‘translate’’ command 


.tr \(mi\(em 

is perfectly clear, meaning 
is 

that is, to translate — into —. 


Some characters are automatically translated into others: grave 
and acute ~ accents (apostrophes) become open and close single 
quotes ‘*’; the combination of ‘...” is generally preferable to the dou- 
ble quotes "...". Similarly a typed minus sign becomes a hyphen -. 
To print an explicit — sign, use \- . To get a backslash printed, use 
\e. 
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4. Indents and Line Lengths 


troff starts with a line length of 6.5 inches, which some people think is 
too wide for 8%x11 paper. To reset the line length, use the .II com- 
mand, as in 


Hl 61 


As with .sp , the actual length can be specified in several ways; inches 
are probably the most intuitive. 


The maximum line length provided by the typesetter is 7.5 inches, by 
the way. To use the full width, you will have to reset the default 
physical left margin (‘‘page offset’), which is normally slightly less 
than one inch from the left edge of the paper. This is done by the 
-po command. 


-po 0 
sets the offset as far to the left as it will go. 


The indent command .in causes the left margin to be indented by 
some specified amount from the page offset. If we use .in to move 
the left margin in, and .1 to move the right margin to the left, we can 
make offset blocks of text: 


.in 0.3i 

A 0.33 

text to be set into a block 
ll +0.3i 

.in —0.3i 


will create a block that looks like this: 


Pater noster qui est in caelis sanctificetur nomen tuum; 
adveniat regnum tuum; fiat voluntas tua, sicut in caelo, et in 
terra. .... Amen. 


Notice the use of ‘+’ and ‘—’ to specify the amount of change. These 
change the previous setting by the specified amount, rather than just 
overriding it. The distinction is quite important: .ll +1i makes lines 
one inch longer; .II 1i makes them one inch Jong. 


With .in , .Il and .po , the previous value is used if no argument is 
specified. 


To indent a single line, use the ‘‘temporary indent’? command .ti. 
For example, this line was produced with the command 


ti 3 
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Three of what? The default unit for .ti, as for most horizontally 
oriented commands (.1], .in, .po), is ems; an em is roughly the width 
of the letter ‘‘m’’ in the current point size. (Precisely, a em in size p 
is p points.) Although inches are usually clearer than ems to people 
who don’t set type for a living, ems have a place: they are a measure 
of size that is proportional to the current point size. If you want to 
make text that keeps its proportions regardless of point size, you 
should use ems for all dimensions. Ems can be specified as scale fac- 
tors directly, as in .ti 2.5m. 


Lines can also be indented negatively if the indent is already positive: 
ti —0.3i 


causes the next line to be moved back three tenths of an inch. Thus 
to make a decorative initial capital, we indent the whole paragraph, 
then move the letter ‘‘P’’ back with a .ti command: 


cetur nomen tuum; adveniat regnum 
tuum; fiat voluntas tua, sicut in 
caelo, et in terra. ... Amen. 


P= noster qui est in caelis sanctifi- 


Of course, there is also some trickery to make the ‘‘P”’ bigger (just a 
““\s36P\s0”), and to move it down from its normal position (see the 
section on local motions). Also, the line ’in -.3i is inserted just 
before “‘fiat’? to move the indent so that ‘‘caelo” lines up under the 
iho oe 


5. Tabs 


Tabs (the ASCII “horizontal tab’ character) can be used to produce 
output in columns, or to set the horizontal position of output. Typi- 
cally tabs are used only in unfilled text. Tab stops are set by default 
every half inch from the current indent, but can be changed by the 
.ta command. To set stops every inch, for example, 


.ta 1i 2i 31 41 51 61 
Unfortunately the stops are left-justified only (as on a typewriter), so 
lining up columns of right-justified numbers can be painful. If you 


have many numbers, or if you need more complicated table layout, 
don’t use troff directly; use the tbl program described in [3]. 


For a handful of numeric columns, you can do it this way: Precede 
every number by enough blanks to make it line up when typed. 
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nf 
sta li 2i 33 

1 tab 2tab 3 
40 tab 50 tab 60 
700 tab 800 tab 900 
fi 


Then change each leading blank into the string \0. This is a charac- 
ter that does not print, but that has the same width as a digit. When 
printed, this will produce 


1 2 3 
40 50 60 
700 800 900 


It is also possible to fill up tabbed-over space with some character 
other than blanks by setting the ‘‘tab replacement character” with the 
.te command: 


.ta 1.51 2.51 
.te \(ru (\(tu is "_") 
Name tab Age tab 


produces 
Name —______ sd Age _____ 


To reset the tab replacement character to a blank, use .te with no 
argument. (Lines can also be drawn with the \l command, described 
in Section 6.) 


troff also provides a very general mechanism called ‘“‘fields’’ for setting 
up complicated columns. (This is used by tbl). We will not go into it 
in this paper. 


6. Local Motions: Drawing Lines and 
Characters 


2sy 


Remember “‘Area = mr“”’ and the big ‘“‘P”’ in the Paternoster. How 
are they done? troff provides a host of commands for placing charac- 
ters of any size at any place. You can use them to draw special char- 
acters or to tune your output for a particular appearance. Most of 
these commands are straightforward, but messy to read and tough to 
type correctly. 
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If you won’t use eqn, subscripts and superscripts are most easily done 
with the half-line local motions \u and \d. To go back up the page 
half a point-size, insert a \u at the desired place; to go down, insert a 
\. (\u and \d should always be used in pairs, as explained below.) 
Thus 


Area = \(*pr\u2\d 
produces 
Area = ar 


To make the ‘‘2”’ smaller, bracket it with \s—2...\s0. Since \u and 
\d refer to the current point size, be sure to put them either both 
inside or both outside the size changes, or you will get an unbalanced 
vertical motion. 


Sometimes the space given by \u and \d isn’t the right amount. The 
\v command can be used to request an arbitrary amount of vertical 
motion. The in-line command 


\v’(amount)’ 


causes motion up or down the page by the amount specified in 
‘‘(amount).”’ For example, to move the ‘‘P’’ down, we used 


.in +0.6i (move paragraph in) 
ll —2.25i (shorten lines) 
.ti 0.31 (move P back) 


\36\v’2’P\v’-2\sOater noster qui est in caelis ... 


A minus sign causes upward motion, while no sign or a plus sign 
means down the page. Thus \v’—2' causes an upward vertical motion 
of two line spaces. 


There are many other ways to specify the amount of motion— 


\v’0.11 

\v’3p’ 

\v’-0.5m’ 
and so on are all legal. Notice that the scale specifier i or p or m 
goes inside the quotes. Any character can be used in place of the 


quotes; this is also true of all other troff commands described in this 
section. 


Since troff does not take within-the-line vertical motions into account 
when figuring out where it is on the page, output lines can have unex- 
pected positions if the left and right ends aren’t at the same vertical 
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position. Thus \v, like \u and \d, should always balance upward 
vertical motion in a line with the same amount in the downward 
direction. 


Arbitrary horizontal motions are also available—\h is quite analo- 
gous to \v, except that the default scale factor is ems instead of line 
spaces. As an example, 


\h’-0.17 
causes a backwards motion of a tenth of an inch. As a practical 
matter, consider printing the mathematical symbol “>>”. The 
default spacing is too wide, so eqn replaces this by 

>\h’-0.3m’> 


to produce >>. 


Frequently \h is used with the “‘width function’? \w to generate 
motions equal to the width of some character string. The construc- 
tion 

\w’ thing’ 
is a number equal to the width of “thing” in machine units (1/432 


inch). All troff computations are ultimately done in these units. To 
move horizontally the width of an ‘‘x’”’, we can say 


\h’\w’x’v’ 
As we mentioned above, the default scale factor for all horizontal 
dimensions is m, ems, so here we must have the u for machine units, 


or the motion produced will be far too large. troff is quite happy with 
the nested quotes, by the way, so long as you don’t leave any out. 


As a live example of this kind of construction, all of the command 
names in the text, like .sp, were done by overstriking with a slight 
offset. The commands for .sp are 


sp\h’-\w’ sp’u’\h’1u’.sp 


That is, put out “‘.sp’’, move left by the width of ‘“.sp’’, move right 1 
unit, and print “‘.sp’”’ again. (Of course there is a way to avoid typing 
that much input for each command name, which we will discuss in 
Section 11.) 


There are also several special-purpose troff commands for local 
motion. We have already seen \0, which is an unpaddable white 
space of the same width as a digit. ‘‘Unpaddable”’ means that it will 
never be widened or split across a line by line justification and filling. 
There is also \ (blank), which is an unpaddable character the width 
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of a space, \| , which is half that width, \~ , which is one quarter of 
the width of a space, and \& , which has zero width. (This last one 
is useful, for example, in entering a text line which would otherwise 
begin with a ‘.’’.) 


The command \o, used like 
\o’set of characters’ 


causes (up to 9) characters to be overstruck, centered on the widest. 
This is nice for accents, as in 


syst\o"e\(ga"me t\o"e\(aa"l\o" e\(aa" phonique 
which makes 
syst? me téléphonique 


The accents are \(ga and \(aa, or \~ and \~; remember that each is 
just one character to troff. 


You can make your own overstrikes with another special convention, 
\z, the zero-motion command. \zx suppresses the normal horizontal 
motion after printing the single character x, so another character can 
be laid on top of it. Although sizes can be changed within \o, it 
centers the characters on the widest, and there can be no horizontal 
or vertical motions, so \z may be the only way to get what you want: 


Bb 


is produced by 


sp 2 
\s8\z\ (sq\s14\z\(sq\s22\z\(sq\s36\ (sq 


The .sp is needed to leave room for the result. 

As another example, an extra-heavy semicolon that looks like 
3 instead of ; or j 

can be constructed with a big comma and a big period above it: 
\st+6\z,\v’—0.25m’.\v’0.25m’\s0 

““0.25m” is an experimentally-derived constant. 


A more ornate overstrike is given by the bracketing function \b, 
which piles up characters vertically, centered on the current baseline. 
Thus we can get big brackets, constructing them with piled-up smaller 
pieces: 


8—I4 Programmer's Guide: CTIX Supplement 


i, 


(J) 


by typing in only this: 
.Sp 
\b’/\(t\(Ik\ (ib? \b’ \(ie\ (If? x \b’\re\ (rf? Nb’ \Gt\ (rk\ (rb 


troff also provides a convenient facility for drawing horizontal and 
vertical lines of arbitrary length with arbitrary characters. \I‘1i’ 


draws a line one inch long, like this: _____. The length can 
be followed by the character to use if the _ isn’t appropriate; \1’0.5i.’ 
draws a half-inch line of dots: ......... The construction \L is 


entirely analogous, except that it draws a vertical line instead of hor- 
izontal. 


7. Strings 


Obviously if a paper contains a large number of occurrences of an 
acute accent over a letter ‘“‘e’’, typing \o"e\ “" for each € would be a 
great nuisance. 


Fortunately, troff provides a way in which you can store an arbitrary 
collection of text in a “‘string’’, and thereafter use the string name as 
a shorthand for its contents. Strings are one of several troff mechan- 
isms whose judicious use lets you type a document with less effort and 
organize it so that extensive format changes can be made with few 
editing changes. 


A reference to a string is replaced by whatever text the string was 
defined as. Strings are defined with the command .ds. The line 


.ds e \o"e\"" 
defines the string e to have the value \o"e\ ~" 


String names may be either one or two characters long, and are 
referred to by \*x for one character names or \*(xy for two charac- 
ter names. Thus to get tlphone, given the definition of the string e as 
above, we can say t\*el\ *ephone. 


If a string must begin with blanks, define it as 
ds xx " text 


The double quote signals the beginning of the definition. There is no 
trailing quote; the end of the line terminates the string. 


A TROFF Tutorial 8—I5 


A string may actually be several lines long; if troff encounters a \ at 
the end of any line, it is thrown away and the next line added to the 
current one. So you can make a long string simply by ending each 
line but the last with a backslash: 


.ds xx this \ 
is a very \ 
long string 


Strings may be defined in terms of other strings, or even in terms of 
themselves; we will discuss some of these possibilities later. 


8. Introduction to Macros 


Before we can go much further in troff, we need to learn a bit about 
the macro facility. In its simplest form, a macro is just a shorthand 
notation quite similar to a string. Suppose we want every paragraph 
to start in exactly the same way—with a space and a temporary indent 
of two ems: 


.Sp 
ti +2m 


Then to save typing, we would like to collapse these into one short- 
hand line, a troff “‘command” like 


.PP 
that would be treated by troff exactly as 


.Sp 
ti +2m 


.PP is called a macro. The way we tell troff what .PP means is to 
define it with the .de command: 


.de PP 


Sp 
.ti +2m 


The first line names the macro (we used ‘‘.PP”’ for “‘paragraph’’, and 
upper case so it wouldn’t conflict with any name that troff might 
already know about). The last line ... marks the end of the defini- 
tion. In between is the text, which is simply inserted whenever troff 
sees the ‘‘command” or macro call 
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.PP 
A macro can contain any mixture of text and formatting commands. 


The definition of .PP has to precede its first use; undefined macros 
are simply ignored. Names are restricted to one or two characters. 


Using macros for commonly occurring sequences of commands is crit- 
ically important. Not only does it save typing, but it makes later 
changes much easier. Suppose we decide that the paragraph indent is 
too small, the vertical space is much too big, and roman font should 
be forced. Instead of changing the whole document, we need only 
change the definition of .PP to something like 


.de PP \" paragraph macro 
sp 2p 
.ti +3m 


ft R 


and the change takes effect everywhere we used .PP. 


\" is a troff command that causes the rest of the line to be ignored. 
We use it here to add comments to the macro definition (a wise idea 
once definitions get complicated). 


As another example of macros, consider these two which start and 
end a block of offset, unfilled text, like most of the examples in this 


paper: 


.de BS \" start indented block 
sp 

nf 

in +0.3i 

.de BE \" end indented block 
.Sp 

fi 

.in —0.3i 


Now we can surround text like 


Copy to 

John Doe 
Richard Roberts 
Stanley Smith 
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by the commands .BS and .BE, and it will come out as it did above. 
Notice that we indented by .in +0.3i instead of .in 0.31. This way we 
can nest our uses of .BS and BE to get blocks within blocks. 


If later on we decide that the indent should be 0.5i, then it is only 
necessary to change the definitions of .BS and .BE, not the whole 
paper. 


9. Titles, Pages and Numbering 


This is an area where things get tougher, because nothing is done for 
you automatically. Of necessity, some of this section is a cookbook, 
to be copied literally until you get some experience. 


Suppose you want a title at the top of each page, saying just 
left top center top right top 


In roff, one can say 


-he ‘left top’center top’right top’ 
.fo “left bottom’center bottom’right bottom’ 


to get headers and footers automatically on every page. Alas, this 
doesn’t work so easily in troff, a serious hardship for the novice. 
Instead you have to do a lot of specification (or use a macro package, 
which makes it effortless). 


You have to say what the actual title is (easy); when to print it (easy 
enough); and what to do at and around the title line (harder). Tak- 
ing these in reverse order, first we define a macro .NP (for ‘‘new 
page’’) to process titles and the like at the end of one page and the 
beginning of the next: 


.de NP 

‘bp 

‘sp 0.5i 

.tl “left top’center top’right top’ 
‘sp 0.31 


To make sure we’re at the top of a page, we issue a ‘begin page” 
command ‘bp, which causes a skip to top-of-page (we'll explain the ' 
shortly). Then we space down half an inch, print the title (the use of 
.t] should be self explanatory; later we will discuss parameterizing the 
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titles), space another 0.3 inches, and we’re done. 


To ask for .NP at the bottom of each page, we have to say something 
like ‘“‘when the text is within an inch of the bottom of the page, start 
the processing for a new page.” This is done with a “‘when” com- 
mand .wh: 


.wh -li NP 


(No “‘.”’ is used before NP; this is simply the name of a macro, not a 
macro call.) The minus sign means “measure up from the bottom of 
the page,” so “‘—1i’? means “‘one inch from the bottom.” 


The .wh command appears in the input outside the definition of .NP; 
typically the input would be 


.de NP 


ih NP 


Now what happens? As text is actually being output, troff keeps track 
of its vertical position on the page, and after a line is printed within 
one inch from the bottom, the .NP macro is activated. (In the jar- 
gon, the .wh command sets a trap at the specified place, which is 
“sprung” when that point is passed.) .NP causes a skip to the top of 
the next page (that’s what the ‘bp was for), then prints the title with 
the appropriate margins. 


Why ‘bp and ‘sp instead of .bp and .sp? The answer is that .sp and 
.bp, like several other commands, cause a break to take place. That 
is, all the input text collected but not yet printed is flushed out as 
soon as possible, and the next input line is guaranteed to start a new 
line of output. If we had used .sp or .bp in the .NP macro, this 
would cause a break in the middle of the current output line when a 
new page is started. The effect would be to print the left-over part of 
that line at the top of the page, followed by the next input line on a 
new output line. This is nor what we want. Using ’ instead of . for a 
command tells troff that no break is to take place—the output line 
currently being filled should not be forced out before the space or new 
page. 

The list of commands that cause a break is short and natural: 

.bp .br .ce .fi .nf .sp .in .ti 


All others cause no break, regardless of whether you use a. ora’ 
If you really need a break, add a .br command at the appropriate 
place. 
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One other thing to beware of—if you’re changing fonts or point sizes 
a lot, you may find that if you cross a page boundary in an unex- 
pected font or size, your titles come out in that size and font instead 
of what you intended. Furthermore, the length of a title is indepen- 
dent of the current line length, so titles will come out at the default 
length of 6.5 inches unless you change it, which is done with the .It 
command. 


There are several ways to fix the problems of point sizes and fonts in 
titles. For the simplest applications, we can change .NP to set the 
proper size and font for the title, then restore the previous values, 
like this: 


.de NP 

‘bp 

‘sp 0.5i 

ft R \" set title font to roman 
ps 10 \" and size to 10 point 
It 61 \" and length to 6 inches 
.tl “left’center’right’ 

-ps \" revert to previous size 
.ft P \" and to previous font 


‘sp 0.31 


This version of .NP does not work if the fields in the .tl command 
contain size or font changes. To cope with that requires troff’s 
“environment”? mechanism, which we will discuss in Section 13. 


To get a footer at the bottom of a page, you can modify .NP so it 
does some processing before the ‘bp command, or split the job into a 
footer macro invoked at the bottom margin and a header macro 
invoked at the top of the page. These variations are left as exercises. 


Output page numbers are computed automatically as each page is pro- 
duced (starting at 1), but no numbers are printed unless you ask for 
them explicitly. To get page numbers printed, include the character 
% in the .tl line at the position where you want the number to 
appear. For example 


tl i$ % ” 


centers the page number inside hyphens. You can set the page 
number at any time with either .bp n, which immediately starts a new 
page numbered n, or with .pn n, which sets the page number for the 
next page but doesn’t cause a skip to the new page. Again, .bp +n 
sets the page number to n more than its current value; .bp means 
«bp +1. 
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10. Number Registers and Arithmetic 


troff has a facility for doing arithmetic, and for defining and using 
variables with numeric values, called number registers. Number regis- 
ters, like strings and macros, can be useful in setting up a document 
so it is easy to change later. And of course they serve for any sort of 
arithmetic computation. 


Like strings, number registers have one or two character names. 
They are set by the .nr command, and are referenced anywhere by 
\nx (one character name) or \n(xy (two character name). 


There are quite a few pre-defined number registers maintained by 
troff, among them % for the current page number; nl for the current 
vertical position on the page; dy, mo and yr for the current day, 
month and year; and .s and .f for the current size and font. (The 
font is a number from 1 to 4.) Any of these can be used in computa- 
tions like any other register, but some, like .s and .f, cannot be 
changed with .nr. 


As an example of the use of number registers, in the —ms macro 
package [4], most significant parameters are defined in terms of the 
values of a handful of number registers. These include the point size 
for text, the vertical spacing, and the line and title lengths. To set 
the point size and vertical spacing for the following paragraphs, for 
example, a user may say 


-nr PS 9 
nr VS 11 


The paragraph macro .PP is defined (roughly) as follows: 


.de PP 
-ps \\n(PS \" reset size 
.vs \\n(VSp \" spacing 


ft R \" font 
sp 0.5v \" half a line 
ti +3m 


This sets the font to Roman and the point size and line spacing to 
whatever values are stored in the number registers PS and VS. 


Why are there two backslashes? This is the eternal problem of how 
to quote a quote. When troff originally reads the macro definition, it 
peels off one backslash to see what’s coming next. To ensure that 
another is left in the definition when the macro is used, we have to 
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put in two backslashes in the definition. If only one backslash is 
used, point size and vertical spacing will be frozen at the time the 
macro is defined, not when it is used. 


Protecting by an extra layer of backslashes is only needed for \n, \*, 
\$ (which we haven’t come fo yet), and \ itself. Things like \s, \f, 
\h, \v, and so on do not need an extra backslash, since they are con- 
verted by troff to an internal code immediately upon being seen. 


Arithmetic expressions can appear anywhere that a number is 
expected. As a trivial example, 


nr PS \\n(PS-2 


decrements PS by 2. Expressions can use the arithmetic operators +, 
-, *, /, % (mod), the relational operators >, >=, <, <=, =, and != 
(not equal), and parentheses. 


Although the arithmetic we have done so far has been straightfor- 
ward, more complicated things are somewhat tricky. First, number 
registers hold only integers. troff arithmetic uses truncating integer 
division, just like Fortran. Second, in the absence of parentheses, 
evaluation is done left-to-right without any operator precedence 
(including relational operators). Thus 


7*-44+3/13 


becomes ‘‘-1”’._ Number registers can occur anywhere in an expres- 
sion, and so can scale indicators like p, i, m, and so on (but no 
spaces). Although integer division causes truncation, each number 
and its scale indicator is converted to machine units (1/432 inch) 
before any arithmetic is done, so 1i/2u evaluates to 0.5i correctly. 


The scale indicator u often has to appear when you wouldn't expect 
it—in particular, when arithmetic is being done in a context that 
implies horizontal or vertical dimensions. For example, 


7/21 


would seem obvious enough—3¥% inches. Sorry. Remember that the 
default units for horizontal parameters like .I] are ems. That's really 
“7 ems / 2 inches,’ and when translated into machine units, it 
becomes zero. How about 


ll 7i/2 


Sorry, still no good—the ‘‘2”’ is ‘‘2 ems’’, so ‘‘7i/2” is small, although 
not zero. You must use 


Hl 7i/2u 
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So again, a safe rule is to attach a scale indicator to every number, 
even constants. 


For arithmetic done within a .nr command, there is no implication of 
horizontal or vertical dimension, so the default units are “‘units’’, and 
7i/2 and 7i/2u mean the same thing. Thus 


nr Il 7i/2 
I \\n(lu 


does just what you want, so long as you don’t forget the u on the .Il 
command. 


11. Macros with Arguments 


The next step is to define macros that can change from one use to the 
next according to parameters supplied as arguments. To make this 
work, we need two things: first, when we define the macro, we have 
to indicate that some parts of it will be provided as arguments when 
the macro is called. Then when the macro is called we have to pro- 
vide actual arguments to be plugged into the definition. 


Let us illustrate by defining a macro .SM that will print its argument 
two points smaller than the surrounding text. That is, the macro call 


.SM TROFF 
will produce TROFF. 
The definition of .SM is 


.de SM 
\s-2\\$1\s+2 


Within a macro definition, the symbol \\$n refers to the nth argu- 
ment that the macro was called with. Thus \\$1 is the string to be 
placed in a smaller point size when .SM is called. 


As a slightly more complicated version, the following definition of 
.SM permits optional second and third arguments that will be printed 
in the normal size: 


.de SM 
\N\S$3\s-2\\$1\s+2\\$2 


Arguments not provided when the macro is called are treated as 
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empty, so 
.SM TROFF ). 
produces TROFF), while 
.SM TROFF ). ( 


produces (TROFF). It is convenient to reverse the order of arguments 
because trailing punctuation is much more common than leading. 


By the way, the number of arguments that a macro was called with is 
available in number register .$ . 


The following macro .BD is the one used to make the “bold roman” 
we have been using for troff command names in text. It combines 
horizontal motions, width computations, and argument rearrange- 
ment. 


.de BD 
V@\AS3\FINAS INA Aw \AS Put Lu \ASI\EP\\S2 


The \h and \w commands need no extra backslash, as we discussed 
above. The \& is there in case the argument begins with a period. 


Two backslashes are needed with the \\$n commands, though, to 
protect one of them when the macro is being defined. Perhaps a 
second example will make this clearer. Consider a macro called .SH 
which produces section headings with the sections numbered automat- 
ically, and the title in bold in a smaller size. The use is 


SH "Section title ..." 


(If the argument to a macro is to contain blanks, then it must be sur- 
rounded by double quotes, unlike a string, where only one leading 
quote is permitted.) 


Here is the definition of the .SH macro: 
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-nr SH 0 \" 
.de SH 

.sp 0.3: 

ft B 

-nr SH \\n(SH+1— -\" increment number 
_ps \\n(PS-1 \" decrease PS 
\\n(SH. \\$1 \" number. title 

-ps \\n(PS \" restore PS 

ssp 0.3: 

ft R 


initialize section number 


The section number is kept in number register SH, which ts incre- 
mented each time just before it is used. (A number register may 
have the same name as a macro without conflict but a string may 
not.) 


We used \\n(SH instead of \n(SH and \\n(PS instead of \n(PS. If 
we had used \n(SH, we would get the value of the register at the 
time the macro was defined, not at the time it was used. If that’s 
what you want, fine, but not here. Similarly, by using \\n(PS, we 
get the point size at the time the macro is called. 


As an example that does not involve numbers, recall our .NP macro 
which had a 


.tl “left’center’right’ 
We could make these into parameters by using instead 
tL ONVACLTA\AA(CT’\A4(RT? 


so the title comes from three strings called LT, CT and RT. If these 
are empty, then the title will be a blank line. Normally CT would be 
set with something like 


.ds CT - %- 


to give just the page number between hyphens, but a user could sup- 
ply private definitions for any of the strings. 
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12. Conditionals 


Suppose we want the .SH macro to leave two extra inches of space 
just before section 1, but nowhere else. The cleanest way to do that 
is to test inside the .SH macro whether the section number is 1, and 
add some space if it is. The .if command provides the conditional 
test that we can add just before the heading line is output: 


.if \\n(SH=1 «sp 2i \" first section only 


The condition after the .if can be any arithmetic or logical expression. 
If the condition is logically true, or arithmetically greater than zero, 
the rest of the line is treated as if it were text—here a command. If 
the condition is false, or zero or negative, the rest of the line is 
skipped. 


It is possible to do more than one command if a condition is true. 
Suppose several operations are to be done before section 1. One pos- 
sibility is to define a macro .S1 and invoke it if we are about to do 
section 1 (as determined by an .if). 


.de S1 
--- processing for section 1 --- 
.de SH 


if \\n(SH=1 .S1 


An alternate way is to use the extended form of the .if, like this: 


if \\n(SH=1 \{--- processing 
for section 1 ----\} 


The braces \{ and \} must occur in the positions shown or you will 
get unexpected extra lines in your output. troff also provides an “if- 
else”’ construction, which we will not go into here. 


A condition can be negated by preceding it with ! ; we get the same 
effect as above (but less clearly) by using 


wif '\\n(SH>1 .S1 


There are a handful of other conditions that can be tested with .if. 
For example, is the current page even or odd? 
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.if o .tl ’odd page title’’- % -’ 
.if e .tl ’- % -” even page title’ 


gives facing pages different titles and page numbers on the outside 
edge when used inside an appropriate new page macro. 


Two other conditions are t and n, which tell you whether the for- 
matter is troff or nroff. 


.if t troff stuff ... 
.if n nroff stuff ... 


Finally, string comparisons may be made in an . if: 
if *string]’string2’ stuff 


does ‘“‘stuff’’ if string/ is the same as string2. The character separat- 
ing the strings can be anything reasonable that is not contained in 
either string. The strings themselves can reference strings with \* , 
arguments with \$ , and so on. 


13. Environments 


As we mentioned, there is a potential problem when going across a 
page boundary: parameters like size and font for a page title may 
well be different from those in effect in the text when the page boun- 
dary occurs. troff provides a very general way to deal with this and 
similar situations. There are three ‘“‘environments’’, each of which 
has independently settable versions of many of the parameters associ- 
ated with processing, including size, font, line and title lengths, 
fill/nofill mode, tab stops, and even partially collected lines. Thus the 
titling problem may be readily solved by processing the main text in 
one environment and titles in a separate one with its own suitable 
parameters. 


The command .ev n shifts to environment n; n must be 0, 1 or 2. 
The command .ev with no argument returns to the previous environ- 
ment. Environment names are maintained in a stack, so calls for dif- 
ferent environments may be nested and unwound consistently. 


Suppose we say that the main text is processed in environment 0, 
which is where troff begins by default. Then we can modify the new 
page macro .NP to process titles in environment 1 like this: 
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.de NP 


.ev 1 \" shift to new environment 
It 61 \" set parameters here 
ft R 
ps 10 
. any other processing ... 
ev \" return to previous environment 


It is also possible to initialize the parameters for an environment out- 
side the .NP macro, but the version shown keeps all the processing in 
one place and is thus easier to understand and change. 


14. Diversions 


There are numerous occasions in page layout when it 1s necessary to 
store some text for a period of time without actually printing it. 
Footnotes are the most obvious example: the text of the footnote 
usually appears in the input well before the place on the page where it 
is to be printed is reached. In fact, the place where it is output nor- 
mally depends on how big it is, which implies that there must be a 
way to process the footnote at least enough to decide its size: without 
printing it. 


troff provides a mechanism called a diversion for doing this process- 
ing. Any part of the output may be diverted into a macro instead of 
being printed, and then at some convenient time the macro may be 
put back into the input. 


The command .di xy begins a diversion—all subsequent output is col- 
lected into the macro xy until the command .di with no arguments is 
encountered. This terminates the diversion. The processed text is 
available at any time thereafter, simply by giving the command 


XY 


The vertical size of the last finished diversion is contained in the 
built-in number register dn. 


As a simple example, suppose we want to implement a “‘keep-release™ 
operation, so that text between the commands .KS and .KE will not 
be split across a page boundary (as for a figure or table). Clearly, 
when a .KS is encountered, we have to begin diverting the output so 
we can find out how big it is. Then when a .KE is seen, we decide 
whether the diverted text will fit on the current page, and print it 
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either there if it fits, or at the top of the next page if it doesn’t. So: 


.de KS \" start keep 

br \" start fresh line 

.ev i \" collect in new environment 
fi \" make it filled text 

.di XX \" collect in XX 

.de KE \" end keep 

.br \" get last partial line 

di \" end diversion 

if \\n(dn>=\\n(.t .bp \" bp if doesn’t fit 
nf \" bring it back in no-fill 

XX \" text 

eV \" return to normal environment 


Recall that number register nl is the current position on the output 
page. Since output was being diverted, this remains at its value when 
the diversion started. dn is the amount of text in the diversion; .t 
(another built-in register) is the distance to the next trap, which we 
assume is at the bottom margin of the page. If the diversion is large 
enough to go past the trap, the .if is satisfied, and a .bp is issued. In 
either case, the diverted output is then brought back with .XX. It is 
essential to bring it back in no-fill mode so troff will do no further 
processing on it. 


This is not the most general keep-release, nor is it robust in the face 
of all conceivable inputs, but it would require more space than we 
have here to write it in full generality. This section is not intended to 
teach everything about diversions, but to sketch out enough that you 
can read existing macro packages with some comprehension. 
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Appendix A: Laser Printer Character Set 


These characters exist in roman, italic, and bold. To get the one on 
the left, type the four-character name on the right. 


© \(ff fi \(fi fl \(fl fi \(Fi fl \(FI 


— \(tu — \(em % \(14 % \(i2 % \(34 
© \(co ° \(de + \(dg * Vim ¢ \(ct 
© \(rg @ \(bu Oo \(sq@ = \(hy 

The following are special-font characters: 
+ \(pl — \(mi x  \(mu + \(di 
=  \(eq = \G= = \P= = \(<= 
# \('= + \(+- -  \(no / \(sl 
~  \(ap =. N= «x  \(pt Vo \(gr 
> \(-> - \(<- t \(ua ‘ \(da 
JS \(is a \(pd o  \(if Vo \(sr 
Cc \(sb > \(sp U \(cu nN \(ca 
Cc \Gb > \Gp € \(mo O \(es 
-  \(aa ~  \(ga Oo \Ci @® \(bs 
§  \(se +  \(dd ww \ (Ih or \(th 
( \{(t )  \Ct .  \de ] \Ge 
L \db J \(rb | \f 1 \Gf 
1  \(k t \(tk 1  \(bv s \(ts 
| \(or | \(or — \Ql \(rn 
* \C* 


These four characters also have two-character names. The ~ is the 
apostrophe on terminals; the ~ is the other quote mark. 


“oN ye NS =i NS a. NE, 
These characters exist only on the special font, but they do not have 
four-character names: 
in { } < > - 7 \ # @ 
For greek, precede the roman letter by \(* to get the corresponding 
greek; for example, \(*a is a. 
abgdezyhikImncoprstufxqw 
aBySeCnOckrApvéotpoTtVdxXbo 


ABGDEZYHIKLMNCOPRS TUFXOQW 
ABP AEZHOIKAMNZEOIIPLTYOXVO 


1. In some character sets, the bold \(sq produces a solid (filled) box. 
2. Ifa greek character does not exist on the special font, the equivalent character 
in the current font is printed. 
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9 


MM — Memorandum Macros 


1. Introduction 
1.1 Purpose 


This memorandum is the user’s guide and reference manual for the 
Memorandum Macros (MM), a general-purpose package of text for- 
matting macros for use with the UNIX text formatters nroff and troff. 


The purpose of MM is to provide a unified, consistent, and flexible 
tool for producing many common types of documents. Although the 
UNIX time-sharing system provides other macro packages for various 
specialized formats, MM has become the standard, general-purpose 
macro package for most documents. 


MM can be used to produce: 
e Letters 


e Reports 


Technical Memoranda 


Released Papers 


Manuals 
e Books. 


The uses of MM range from single-page letters to documents of 
several hundred pages in length, such as user guides, design propo- 
sals, etc. 


Source: D.W. Smith, J.R. Mashey, E.C. Pariser (January 1980 Revision), and 
N.W. Smith (June 1980 Revision), MM — Memorandum Macros Piscataway, N.J.: 
Bell Laboratories). 
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1.2 Conventions 


Each section of this memorandum explains a single facility of MM. 
In general, the earlier a section occurs, the more necessary it is for 
most users. Some of the later sections can be completely ignored if 
MM defaults are acceptable. Likewise, each section progresses from 
normal-case to special-case facilities. We recommend reading a sec- 
tion in detail only until there is enough information to obtain the 
desired format, then skimming the rest of it, because some details 
may be of use to just a few people. 


Numbers enclosed in curly brackets ({}) refer to section numbers 
within this document. For example, this is €1.2}. 


Sections that require knowledge of the formatters €1.4} have a bullet 
(e) at the end of their headings. 


In the synopses of macro calls, square brackets ([{]) surrounding an 
argument indicate that it is optional. Ellipses (...) show that the 
preceding argument may appear more than once. 


A reference of the form name(N) points to page name in section N of 
the UNIX User's Manual !"), 


The examples of output in this manual are as produced by troff; nroff 
output would, of course, look somewhat different (Appendix C shows 
both nroff and troff outputs for a simple letter). In those cases in 
which the behavior of the two formatters is truly different, the nroff 
action is described first, with the troff action following in parentheses. 
For example: 


The title is underlined (italic). 


means that the title is underlined in nroff and italic in troff. 


1.3 Overall Structure of a Document 


The input for a document that is to be formatted with MM _ possesses 
four major segments, any of which may be omitted; if present, they 
must occur in the following order: 


Parameter-setting — This segment sets the general style and appear- 
ance of a document. The user can control page width, margin 
justification, numbering styles for headings and lists, page 
headers and footers {9}, and many other properties of the 
document. Also, the user can add macros or redefine existing 
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ones. This segment can be omitted entirely if one is satisfied 
with default values; it produces no actual output, but only per- 
forms the setup for the rest of the document. 


Beginning — This segment includes those items that occur only once, 
at the beginning of a document, e.g., title, author’s name, 
date. 


Body — This segment is the actual text of the document. It may be 
as small as a single paragraph, or as large as hundreds of 
pages. It may have a hierarchy of headings up to seven levels 
deep {4}. Headings are automatically numbered (if desired) 
and can be saved to generate the table of contents. Five addi- 
tional levels of subordination are provided by a set of /ist mac- 
ros for automatic numbering, alphabetic sequencing, and 
“‘marking”’ of list items {5}. The body may also contain vari- 
ous types of displays, tables, figures, references, and footnotes 
£7, 8, 11}. 


Ending — This segment contains those items that occur once only, at 
the end of a document. Included here are signature(s) and 
lists of notations (e.g., ‘“copy to” lists) {6.11}. Certain mac- 
ros may be invoked here to print information that is wholly or 
partially derived from the rest of the document, such as the 
table of contents or the cover sheet for a document {10}. 


The existence and size of these four segments varies widely among 
different document types. Although a specific item (such as date, 
title, author name(s), etc.) may be printed in several different ways 
depending on the document type, there is a uniform way of typing it 
in. 


1.4 Definitions 


The term formatter refers to either of the text-formatting programs 
nroff and troff. 


Requests are built-in commands recognized by the formatters. 
Although one seldom needs to use these requests directly €3.10}, this 
document contains references to some of them. Full details are given 
in the NROFF/TROFF User’s Manual"), For example, the request: 


.Sp 


inserts a blank line in the output. 
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Macros are named collections of requests. Each macro is an abbrevi- 
ation for a collection of requests that would otherwise require repeti- 
tion. MM supplies many macros, and the user can define additional 
ones. Macros and requests share the same set of names and are used 
in the same way. 


Strings provide character variables, each of which names a string of 
characters. Strings are often used in page headers, page footers, and 
lists. They share the pool of names used by requests and macros. A 
string can be given a value via the .ds (define string) request, and its 
value can be obtained by referencing its name, preceded by ‘““\*”’ (for 
1-character names) or ‘‘\*(’’ (for 2-character names). For instance, 
the string DT in MM normally contains the current date, so that the 
input line: 


Today is \*(DT. 
may result in the following ourpur: 
Today is May 1, 1917 
The current date can be replaced, e.g.: 
.ds DT 01/01/79 
or by invoking a macro designed for that purpose {6.7.1}. 


Number registers fill the role of integer variables. They are used for 
flags, for arithmetic, and for automatic numbering. A register can be 
given a value using a .nr request, and be referenced by preceding its 
name by ‘‘\n” (for 1-character names) or “‘\n(’’ (for 2-character 
names). For example, the following sets the value of the register d to 
1 more than that of the register dd: 


.or d 1+\n(dd 


See {14.1} regarding naming conventions for requests, macros, 
strings, and number registers. Appendix E list all macros, strings, 
and number registers defined in MM. 
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1.5 Prerequisites and Further Reading 
1.5.1 Prerequisites 


We assume familiarity with UNIX at the level given in UNIX fer 
Beginners [3] and A Tutorial Introduction to the UNIX Text Editor‘), 
Some familiarity with the request summary in the NROFF/TROFF 
User's Manual") is helpful. 


1.5.2 Further Reading 


NROFFITROFF User's Manual") provides detailed descriptions of for- 
matter capabilities, while A TROFF Tutorial [5] provides a general 
overview. See Typesetting Mathematics—User’s Guide {6] for instruc- 
tions on formatting mathematical expressions. See rb/(1) and TBL—A 
Program to Format Tables!) for instructions on formatting tabular 
data. 


Examples of formatted documents and of their respective input, as 
well as a quick reference to the material in this manual are given in 
Typing Documents with MM (8] 


2. Invoking the Macros 


This section tells how to access MM, shows UNIX command lines 
appropriate for various output devices, and describes command-line 
flags for MM. 


2.1 The mm Command 


The mm (1) command can be used to print documents using nroff and 
MM; this command invokes nroff with the —cm flag {2.2}. It has 
options to specify preprocessing by tb/ and/or by negn and for postpro- 
cessing by various output filters. Any arguments or flags that are not 
recognized by mm(1), e.g. -rC3, are passed to nroff or to MM, as 
appropriate. The options, which can occur in any order but must 
appear before the file names, are: 
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~T450 


~T450-12 
~T300 
~T300-12 
~T300s 
~T300s-12 
~T4014 
~T37 
-T382 
-T4000a 
-TX 
-Thp 
-T43 
-T40/4 
-T745 


-T2631 


-Tlp 


negn is to be invoked; also causes negn to read 
/usrlpubleqnchar (see eqnchar(7)). 

tbl (1) is to be invoked. 

col (1) is to be invoked. 

the -e option of nroff is to be invoked. 

—mm (uncompacted macros) is to be used instead of 
—cm. 

12-pitch mode is to be used. Be sure the pitch switch 
on the terminal is set to 12. 

output is to a DASI 450. This is the default terminal 
type (unless $TERM is set). 

It is also equivalent to -T1620. 

output is to a DASI 450 in 12-pitch mode. 

output is to a DASI 300 terminal. 

output is to a DAST 300 in 12-pitch mode. 

output is to a DAST 3008S. 

output is to a DAST 3008S in 12-pitch mode. 

output is to a Tektronix 4014. 

output is to a TELETYPE® Model 37. 

output is toa DTC-382. 

output is to a Trendata 4000A. 

output is prepared for an EBCDIC line printer. 
output is to a HP264x (implies -c). 

output is to a TELETYPE Model 43 (implies -c). 
output is to a TELETYPE Model 40/4 (implies —c). 
output is to a Texas Instrument 700 series terminal 
(implies —c). 

output is prepared for a HP2631 printer (where 
—T2631-e and ~T2631-c may be used for expanded 
and compressed modes, respectively) (implies ~c). 
output is to a device with no reverse or partial line 
motions or other special features (implies —-c). 


Any other —T option given does not produce an error; it is equivalent 


to —-TIp. 


A similar command is available for use with troff (see mmr (1)). 
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2.2 The —cm or —mm Flag 


The MM package can also be invoked by including the -cm or -mm 
flag as an argument to the formatter. The —cm flag causes the pre- 
compacted version of the macros to be loaded. The -mm flag causes 
the file /usr/lib/tmac/tmac.m to be read and processed before any 
other files. This action defines the MM macros, sets default values 
for various parameters, and initializes the formatter to be ready to 
process the files of input text. 


2.3 Typical Command Lines 


The prototype command lines are as follows (with the various options 
explained in {2.4} and in the NROFF/TROFF User's Manual (71). 


e Text without tables or equations: 
mm [options] file-name ... 
or nroff [options] -cm file-name ... 
mmt [options] file-name... 
or troff [options} -cm file-name... 


e Text with tables: 
mm -t [options] file-name... 
or tbl filename ... | nroff [options] -cm 
mmt -t [options] file-name ... 
or tbl filename ... | troff [options] -cm 


e Text with equations: 
mm -e [options] file-name ... 


or neqn /usr/pub/eqnchar file-name ... | nroff [options] 
-cm 
mmt —e [options] filename... 

or eqn /usr/pub/eqnchar file-name ... | troff [options] -cm 


e Text with both tables and equations: 
mm —t ~e [options] file-name... 
or tbl filename ... | neqn /usr/pub/eqnchar — | nroff 
[options] —cm 
mmt —t —e [options] file-name ... 
or tbl file-name ... | eqn /usr/pub/eqnchar — | _troff 
[options] -cm 


When formatting a document with nroff, the output should normally 
be processed for a specific type of terminal, because the output may 
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require some features that are specific to a given terminal, e.g., 
reverse paper motion or half-line paper motion in both directions. 
Some commonly-used terminal types and the command _ lines 
appropriate for them are given below. See {2.4} as well as 300(1), 
450(1), 40/4(1), hp (1), col(Qi), and terminals (7) for further informa- 
tion. 


e DASI 450 in 10-pitch, 6 lines/inch mode, with 0.75 inch 
offset, and a line length of 6 inches (60 characters) where this 
is the default terminal type so no —T option is needed (unless 
$TERM is set to another value): 

mm file-name... 
or nroff -T450 -h -cm file-name... 


e DASI 450 in 12-pitch, 6 lines/inch mode, with 0.75 inch 
offset, and a line length of 6 inches (72 characters): 
mm ~12 file-name... 
or nroff -T450—12 —-h -cm file-name... 
or, to increase the line length to 80 characters and decrease the 
offset to 3 characters: 
mm —12 -rW80 —rQ3 file-name... 
or nroff -T450-12 -rW80 -rO3 —-h -cm file-name... 


e Hewlett-Packard HP264x CRT family: 
mm —Thp file-name ... 
or nroff—cm file-name... | col | hp 


e Any terminal incapable of reverse paper motion and also lack- 
ing hardware tab stops (Texas Instruments 700 series, etc.): 
mm —T745 file-name... 
or nroff —cm file-name... | col -x 


e Versatec printer (see vp (1) for additional details): 
vp [vp-options] "mm -rT2 —c file-name ..." 
or vp [vp-options] "nroff -rT2 -cm file-name ... | col" 


Of course, tbi/(1) and egn(1)/neqn, if needed, must be invoked as 
shown in the command line prototypes at the beginning of this sec- 
tion. 


If two-column processing 12.4} is used with nroff, either the —c 
option must be specified to mm(1),' or the nroff output must be 


1. Note that mm(1) uses col(1) automatically for many of the terminal types 


{2.1}. 
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postprocessed by col(1). In the latter case, the —T37 terminal type 
must be specified to nroff, the —h option must nor be specified, and 
the output of co/(1) must be processed by the appropriate terminal 
filter (e.g., 450(1)); mm(1) with the -c option handles all this 
automatically. 


2.4 Parameters that Can Be Set from the Command 
Line 


Number registers are commonly used within MM to hold parameter 
values that control various aspects of output style. Many of these can 
be changed within the text files via .nr requests. In addition, some of 
these registers can be set from the command line itself, a useful 
feature for those parameters that should nor be permanently embed- 
ded within the input text itself. If used, these registers (with the pos- 
sible exception of the register P— see below) must be set on the com- 
mand line (or before the MM macro definitions are processed) and 
their meanings are: 


-rAn for n = 1 has the effect of invoking the .AF macro without 
an argument {6.7.2}. If n = 2 allows for usage of the Bell 
System logo, if available, on a printing device (currently 
available for the Xerox 9700 only). 


-rCn_ n sets the type of copy (e.g., DRAFT) to be printed at the 
bottom of each page. See {9.5}. 
n = 1 for OFFICIAL FILE COPY. 
n = 2 for DATE FILE COPY. 
n = 3 for DRAFT with single-spacing and default paragraph 
style. 
n = 4 for DRAFT with double-spacing and 10 space para- 
graph indent. 


-1D1_ sets debug mode. This flag requests the formatter to attempt 
to continue processing even if MM detects errors that would 
otherwise cause termination. It also includes some debug- 
ging information in the default page header (9.2, 12.3}. 


-rEn controls the font of the Subject/Date/From fields. If n is 1 
then these fields are bold (default for troff) and if n is 0 
then these fields are roman (regular text—default for nroff). 


-rLk sets the length of the physical page to & lines.? The default 
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value is 66 lines per page. This parameter is used, for 
example, when directing output to a Versatec printer. 


-rNn_ specifies the page numbering style. When n is 0 (default), 
all pages get the (prevailing) header {9.2}. When n is 1, 
the page header replaces the footer on page 1 only. When n 
is 2, the page header is omitted from page 1. When n is 3, 
“‘section-page’’ numbering {4.5} occurs (see .FD {8.3} and 
.RP {11.4} for footnote and reference numbering in sec- 
tions). When n is 4, the default page header is suppressed; 
however a user-specified header is not affected. When n is 
5, “‘section-page”’ and ‘‘section-figure’’ numbering occurs. 


n Page | Pages 2ff. 

0 header header 

1 header replaces footer header 

2 no header header 

3. ‘‘section-page”’ as footer same as page 1 

4 no header no header unless 
.PH defined 

5___same as 3-with “‘section-figure’ same as page 1 


The contents of the prevailing header and footer do nor 
depend on the value of the number register N; N only con- 
trols whether and where the header (and, for N=3 or 5, the 
footer) is printed, as well as the page numbering style. In 
particular, if the header and footer are null £9.2, 9.5}, the 
value of N is irrelevant. 


-rOk offsets output k spaces to the right.” It is helpful for adjust- 
ing output positioning on some terminals. The default offset 
if this register is not set on the command line is 0.75 inches. 


NOTE 


The register name is the capital letter ““O’’, nor the 
digit zero (0). 


2. For nroff, k is an unscaled number representing lines or character positions; for 
troff, k must be scaled. 
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-rPn_ specifies that the pages of the document are to be numbered 
starting with n. This register may also be set via a .nr 
request in the input text. 


-rSn_ sets the point size and vertical spacing for the document. 
The default n is 10, i.e., 10-point type on 12-point vertical 
spacing, giving 6 lines per inch {12.9}. This parameter 
applies to troff only. 


-rTn_ provides register settings for certain devices. If n is 1, then 
the line length and page offset are set to 80 and 3, respec- 
tively. Setting n to 2 changes the page length to 84 Jines per 
page and inhibits underlining; it is meant for output sent to 
the Versatec printer. The default value for n is 0. This 
parameter applies to nroff only. 


-rU1 controls underlining of section headings. This flag causes 
only letters and digits to be underlined. Otherwise, all char- 
acters (including spaces) are underlined {4.2.2.4.2}. This 
parameter applies to nroff only. 


-rWk page width (i.e., line length and title length) is set to k.” 
This can be used to change the page width from the default 
value of 6 inches (60 characters in 10 pitch or 72 characters 
in 12 pitch). 


2.5 Omission of —cm or —mm 


If a large number of arguments is required on the command line, it 
may be convenient to set up the first (or only) input file of a docu- 
ment as follows: 


zero or more initializations of registers listed in {2.4} 
.so /usr/lib/tmac/tmac.m 
remainder of text 


In this case, one must nor use the -cm or —mm flag (nor the mm (1) 
or mmt(1) command); the .so request has the equivalent effect, but 
the registers in {2.4} must be initialized before the .so request, 
because their values are meaningful only if set before the macro 
definitions are processed. When using this method, it is best to 
“lock’’ into the input file only those parameters that are seldom 
changed. For example: 
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.nr W 80 

nor O 10 

wnr N 3 

so /usr/lib/tmac/tmac.m 
.H1 "INTRODUCTION" 


specifies, for nroff, a line length of 80, a page offset of 10, and 
“‘section-page’’ numbering. 


3. Formatting Concepts 
3.1 Basic Terms 


The normal action of the formatters is to fi// output lines from one or 
more input lines. The output lines may be justified so that both the 
left and right margins are aligned. As the lines are being filled, 
words may also be hyphenated {3.4} as necessary. It is possible to 
turn any of these modes on and off (see .SA {12.2}, Hy {3.4}, and 
the formatter .nf and .-fi requests!7)), Turning off fill mode also turns 
off justification and hyphenation. 


Certain formatting commands (requests and macros) cause the filling 
of the current output line to cease, the line (of whatever length) to be 
printed, and the subsequent text to begin a new output line. This 
printing of a partially filled output line is known as a break. A few 
formatter requests and most of the MM macros cause a break. 


While formatter requests can be used with MM, one must fully under- 
stand the consequences and side-effects that each such request might 
have. Actually, there is little need to use formatter requests; the 
macros described here should be used in most cases because: 


— it is much easier to control (and change at any later point in 
time) the overall style of the document. 


— complicated features (such as footnotes or tables of contents) 
can be obtained with ease. 


— the user is insulated from the peculiarities of the formatter 
language. 


A good rule is to use formatter requests only when absolutely neces- 
sary {3.10}. 
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In order to make it easy to revise the input text at a later time, input 
lines should be kept short and should be broken at the end of clauses; 
each new full sentence must begin on a new line. 


3.2 Arguments and Double Quotes 


For any macro call, a null argument is an argument whose width is 
zero. Such an argument often has a special meaning; the preferred 
form for a null argument is "". Note that omitting an argument is 
not the same as supplying a null argument (for example, see the .MT 
macro in {6.6}). Furthermore, omitted arguments can occur only at 
the end of an argument list, while null arguments can occur any- 
where. 


Any macro argument containing ordinary (paddable) spaces must be 
enclosed in double quotes (").” Otherwise, it will be treated as 
several separate arguments. 


Double quotes (") are not permitted as part of the value of a macro 
argument or of a string that is to be used as a macro argument. If 
you must, use two grave accents (‘‘) and/or two acute accents (’’) 
instead. This restriction is necessary because many macro arguments 
are processed (interpreted) a variable number of times; for example, 
headings are first printed in the text and may be (re)printed in the 
table of contents. 


3.3 Unpaddable Spaces 


When output lines are justified to give an even right margin, existing 
spaces in a line may have additional spaces appended to them. This 
may harm the desired alignment of text. To avoid this problem, it is 
necessary to be able to specify a space that cannot be expanded during 
justification, i.e., an unpaddable space. There are several ways to 
accomplish this. 


3. A double quote (") is a single character that must not be confused with two 
apostrophes or acute accents ("’), or with two grave accents (‘‘). 
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First, one may type a backslash followed by a space (“\ "'). This 
pair of characters directly generates an unpaddable space. Second, 
one may sacrifice some seldom-used character to be translated into a 
space upon output. Because this translation occurs after justification, 
the chosen character may be used anywhere an unpaddable space is 
desired. The tilde (~) is often used for this purpose. To use it in 
this way, insert the following at the beginning of the document: 


tr ~ 


If a tilde must actually appear in the output, it can be temporarily 
“recovered” by inserting: 


or 77 


before the place where it is needed. Its previous usage is restored by 
repeating the ‘‘.tr ~’’, but only after a break or after the line contain- 
ing the tilde has been forced out. Note that the use of the tilde in 
this fashion is not recommended for documents in which the tilde is 
used within equations. 


3.4 Hyphenation 


The formatters do not perform hyphenation unless the user requests 
it. Hyphenation can be turned on in the body of the text by specify- 
ing: 

-nr Hy 1 


once at the beginning of the document. For hyphenation within foot- 
notes and across pages, see {8.3}. 


If hyphenation is requested, the formatters will automatically hyphen- 
ate words, if need be. However, the user may specify the hyphena- 
tion points for a specific occurrence of any word by the use of a spe- 
cial character known as a hyphenation indicator, or may specify 
hyphenation points for a small list of words (about 128 characters). 


If the Ayphenation indicator (initially, the two-character sequence 
“\%") appears at the beginning of a word, the word is nor 
hyphenated. Alternatively, it can be used to indicate legal hyphena- 
tion point(s) inside a word. In any case, all occurrences of the 
hyphenation indicator disappear on output. 


The user may specify a different hyphenation indicator: 


.HC [hyphenation-indicator] 
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The circumflex (*) is often used for this purpose; this is done by 
inserting the following at the beginning of a document: 


-HC * 


Note that any word containing hyphens or dashes—also known as em 
dashes—will be hyphenated immediately after a hyphen or dash if it 
is necessary to hyphenate the word, even if the formatter hyphenation 
function is turned off. 


The user may supply, via the .hw request, a small list of words with 
the proper hyphenation points indicated. For example, to indicate 
the proper hyphenation of the word “‘printout,”” one may specify: 


.hw print-out 


3.5 Tabs 


The macros .MT {6.6}, .TC {10.1}, and .CS {10.2} use the for- 
matter .ta request to set tab stops, and then restore the default values* 
of tab settings. Thus, setting tabs to other than the default values is 
the user’s responsibility. 


Note that a tab character is always interpreted with respect to its posi- 
tion on the input line, rather than its position on the output line. In 
general, tab characters should appear only on lines processed in ‘“‘no- 
fill” mode {3.1}. 


Also note that rb/(1) {7.3} changes tab stops, but does nor restore 
the default tab settings. 


3.6 Special Use of the BEL Character 


The non-printing character BEL is used as a delimiter in many mac- 
ros where it is necessary to compute the width of an argument or to 
delimit arbitrary text, e.g., in headers and footers {9}, headings 
{4}, and list marks {5}. Users who include BEL characters in their 


4. Every eight characters in nroff; every % inch in troff. 
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input text (especially in arguments to macros) will receive mangled 
output. 


3.7 Bullets 


A bullet (e) is often obtained on a typewriter terminal by using an 
“‘o” overstruck by a ‘‘+’’. For compatibility with rroff, a bullet string 
is provided by MM. Rather than overstriking, use the sequence: 


\#(BU 


wherever a bullet is desired. Note that the bullet list (.BL) macros 
{5.3.3.2} use this string to automatically generate the bullets for the 
list items. 


3.8 Dashes, Minus Signs, and Hyphens 


Troff has distinct graphics for a dash, a minus sign, and a hyphen, 
while nroff does not. Those who intend to use nroff only may use the 
minus sign (‘‘—’’) for all three. 


Those who wish mainly to use troff should follow the escape conven- 
tions of the NROFF/TROFF User's Manual"), 


Those who want to use both formatters must take care during text 
preparation. Unfortunately, these characters cannot be represented in 
a way that is both compatible and convenient. We suggest the follow- 
ing approach: 


Dash Type \*(EM for each text dash for both nroff and troff. 
This string generates an em dash (—) in troff and “‘ -- 
in nroff. Note that the dash list (.DL) macros {5.3.3.3} 
automatically generate the em dash for each list item. 


“6D 


Hyphen Type and use as is for both formatters. Nroff will 
print it as is, and ¢troff will print ‘‘-”* (a true hyphen). 


Minus Type “‘\~’’ for a true minus sign, regardless of formatter. 
Nroff will effectively ignore the ‘\’’, while troff will print 
a true minus sign. 
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3.9 Trademark String 


A trademark string \*(Tm is available with MM. This places the 
letters ““TM” one-half line above the text that it follows. 


For example: 

The UNIX\*(Tm User’s Manual is available from the library. 
yields: 

The UNIX™ User's Manual is available from the library. 


3.10 Use of Formatter Requests 


Most formatter requests\"] should not be used with MM because MM 
provides the corresponding formatting functions in a much more 
user-oriented and surprise-free fashion than do the basic formatter 
requests {3.1}. However, some formatter requests are useful with 
MM, namely: 


caf wbr wce 3wde) = ods) efi 2S whwWsaIS. anf wnrs wx 
mm .Ir .tS  .so .sp.ta .ti oth tr |! 


The .fp, .lg, and .ss requests are also sometimes useful for troff. Use 
of other requests without fully understanding their implications very 
often leads to disaster. 


4. Paragraphs and Headings 


This section describes simple paragraphs and section headings. Addi- 
tional paragraph and list styles are covered in {5}. 
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4.1 Paragraphs 


.P [type] 
one or more lines of text. 


This macro is used to begin two kinds of paragraphs. In a /eft- 
justified paragraph, the first line begins at the Ieft margin, while in an 
indented paragraph, it is indented five spaces (see below). 


A document possesses a default paragraph style obtained by specifying 
‘.P” before each paragraph that does not follow a heading 4.2}. 
The default style is controlled by the register Pr. The initial value of 
Pt is 0, which always provides left-justified paragraphs. All para- 
graphs can be forced to be indented by inserting the following at the 
beginning of the document: 


or Pt 1 
All paragraphs will be indented except after headings, lists, and 
displays if the following: 

nr Pt 2 
is inserted at the beginning of the document. 


The amount a paragraph is indented is contained in the register Pi, 
whose default value is 5. To indent paragraphs by, say, 10 spaces, 
insert: 


snr Pi 10 


at the beginning of the document. Of course, both the Pi and Pr 
register values must be greater than zero for any paragraphs to be 
indented. 


The number register Ps controls the amount of spacing between para- 
graphs. By default, Ps is set to 1, yielding one blank space (*% a verti- 
cal space). 


CAUTION 


Values that specify indentation must be unscaled and are 
treated as ‘character positions,” i.e., as a number of ens. In 
troff, an en is the number of points (1 point = 1/72 of an inch) 
equal to half the current point size. In nroff, an en is equal to 
the width of a character. 


9—I8 Programmer's Guide: CTIX Supplement 


Regardless of the value of Pr, an individual paragraph can be forced 
to be left-justified or indented. “‘.P 0” always forces left justification; 
‘“.P 1” always causes indentation by the amount specified by the 
register Pi. 


If .P occurs inside a list, the indent (if any) of the paragraph is added 
to the current list indent {5}. 


Numbered paragraphs may be produced by setting the register Np to 
1. This produces paragraphs numbered within first level headings, 
e.g., 1.01, 1.02, 1.03, 2.01, etc. 


A different style of numbered paragraphs is obtained by using the 
.nP 


macro rather than the .P macro for paragraphs. This produces para- 
graphs that are numbered within second level headings and contain a 
“‘double-line indent’? in which the text of the second line is indented 
to be aligned with the text of the first line so that the number stands 
out. 


.H1 "FIRST HEADING" 
.H 2 "Second Heading" 
nP 

one or more lines of text 


4.2 Numbered Headings 


-H level [heading-text] [heading-suffix] 
zero or more lines of text 


The .H macro provides seven levels of numbered headings, as illus- 
trated by this document. Level 1 is the most major or highest; level 7 
the lowest. 


The heading-suffix is appended to the heading-text and may be used 
for footnote marks which should not appear with the heading text in 
the Table of Contents. 
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CAUTION 


Strictly speaking, there is no need for a .P macro immediately 
after a .H (or .HU {4.3} ), because the .H] macro also per- 
forms the function of the .P macro, and an immediately fol- 
lowing .P is ignored {4.2.2.2}. It is, however, good practice 
to start every paragraph with a .P macro, thereby ensuring that 
all paragraphs uniformly begin with a .P throughout an entire 
document. 


4.2.1 Normal Appearance 


The normal appearance of headings is as shown in this document. 
The effect of .H varies according to the /eve/ argument. First-level 
headings are preceded by two blank lines (one vertical space); all oth- 
ers are preceded by one blank line (‘4 a vertical space). 


.H 1 heading-text gives a bold heading followed by a single blank 
line (% a vertical space). The following text 
begins on a new line and is indented according 
to the current paragraph type. Full capital 
letters should normally be used to make the 
heading stand out. 


-H 2 heading-text yields a bold heading followed by a single 
blank line (% a vertical space). The following 
text begins on a new line and is indented 
according to the current paragraph type. Nor- 
mally, initial capitals are used. 


-H n heading-text for 3<n=7, produces an underlined (italic) 
heading followed by two spaces. The follow- 
ing text appears on the same line, i.e., these 
are run-in headings. 


Appropriate numbering and spacing (horizontal and vertical) occur 
even if the heading text is omitted from a .H macro call. 


Here are the first few .H calls of £4}: 
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-H1 "PARAGRAPHS AND HEADINGS" 
.H 2 "Paragraphs" 

-H 2 "Numbered Headings" 

~H 3 "Normal Appearance." 

.H3 "Altering Appearance of Headings." 

.H 4 "Pre-Spacing and Page Ejection." 

.H 4 "Spacing After Headings." 

.H 4 "Centered Headings." 

.H 4 "Bold, Italic, and Underlined Headings" 
.H 5 "Control by Level." 


4.2.2 Altering Appearance of Headings 


Users satisfied with the default appearance of headings may skip to 
{4.3}. One can modify the appearance of headings quite easily by 
setting certain registers and strings at the beginning of the document. 
This permits quick alteration of a document’s style, because this 
style-control information is concentrated in a few lines, rather than 
being distributed throughout the document. 


4.2.2.1 Pre-Spacing and Page Ejection 


A first-level heading normally has two blank lines (one vertical space) 
preceding it, and all others have one blank line (% a vertical space). 
If a multi-line heading were to be split across pages, it is automati- 
cally moved to the top of the next page. Every first-level heading 
may be forced to the top of a new page by inserting: 


nr Ej 1 
at the beginning of the document. Long documents may be made 
more manageable if each section starts on a new page. Setting Ej toa 


higher value causes the same effect for headings up to that level, i.e., 
a page eject occurs if the heading level is less than or equal to Ej. 
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4.2.2.2 Spacing After Headings 


Three registers control the appearance of text immediately following a 
-H call. They are Hb (heading break level), Hs (heading space level), 
and Hi (post-heading indent). 


If the heading level is less than or equal to Hb, a break {3.1} occurs 
after the heading. If the heading level is less than or equal to Hs, a 
blank line (% a vertical space) is inserted after the heading. Defaults 
for Hb and Hs are 2. If a heading level is greater than Hb and also 
greater than Hs, then the heading (if any) is run into the following 
text. These registers permit headings to be separated from the text in 
a consistent way throughout a document, while allowing easy altera- 
tion of white space and heading emphasis. 


For any stand-alone heading, i.e., a heading not run into the follow- 
ing text, the alignment of the next line of output is controlled by the 
register Hi. If Hi is 0, text is left-justified. If Hi is 1 (the default 
value), the text is indented according to the paragraph type as speci- 
fied by the register Pr {4.1}. Finally, if Hi is 2, text is indented to 
line up with the first word of the heading itself, so that the heading 
number stands out more clearly. 


For example, to cause a blank line (*% a vertical space) to appear after 
the first three heading levels, to have no run-in headings, and to force 
the text following all headings to be left-justified (regardless of the 
value of Pr), the following should appear at the top of the document: 


-nr Hs 3 
snr Hb7 
-nr Hi 0 


4.2.2.3 Centered Headings 


The register Hc can be used to obtain centered headings. A heading 
is centered if its level is less than or equal to Hc, and if it is also 
stand-alone {4.2.2.2}. Hc is 0 initially (no centered headings). 
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4.2.2.4 Bold, Italic, and Underlined Headings 
4.2.2.4.1 Control by Level 


Any heading that is underlined by nroff is made italic by troff. The 
string HF (heading font) contains seven codes that specify the fonts 
for heading levels 1-7. The legal codes, their interpretations, and the 
defaults for HF are: 


HF Code Default 
i 2 3 HF 


Formatter 


no underline underline bold | 3322222 
roman italic bold | 3322222 


Thus, levels 1 and 2 are bold; levels 3 through 7 are underlined in 
nroff and italic in troff. The user may reset HF as desired. Any 
value omitted from the right end of the list is taken to be 1. For 
example, the following would result in five bold levels and two non- 
underlined (roman) levels: 


.ds HF 33333 


4.2.2.4.2 Nroff Underlining Style 


Nroff can underline in two ways. The normal style (.ul request) is to 
underline only letters and digits. The continuous style (.cu request) 
underlines all characters, including spaces. By default, MM attempts 
to use the continuous style on any heading that is to be underlined 
and is short enough to fit on a single line. If a heading is to be 
underlined, but is too long, it is underlined the normal way (i.e., only 
letters and digits are underlined). 


All underlining of headings can be forced to the normal way by using 
the -rU1 flag when invoking nroff {2.4}. 
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4.2.2.4.3 Heading Point Sizes 


The user may also specify the desired point size for each heading Jevel 
with the HP string (for use with troff only). 


-ds HP [ps1] [ps2] [ps3] [ps4] [ps5] [ps6] [ps7] 


By default, the text of headings (.H and .HU) is printed in the same 
point size as the body except that bold stand-alone headings are 
printed in a size one point smaller than the body. The string HP, 
similar to the string HF, can be specified to contain up to seven 
values, corresponding to the seven levels of headings. For example: 


.ds HP 12 12 10 10 10 10 10 


specifies that the first and second level headings are to be printed in 
12-point type, with the remainder printed in 10-point. Note that the 
specified values may also be relative point-size changes, e.g.: 


.ds HP +2 +2 -1-1 


If absolute point sizes are specified, then those sizes will be used 
regardless of the point size of the body of the document. If relative 
point sizes are specified, then the point sizes for the headings will be 
relative to the point size of the body, even if the latter is changed. 


Null or zero values imply that the default size will be used for the 
corresponding heading level. 


CAUTION 


Only the point size of the headings is affected. Specifying a 
large point size without providing increased vertical spacing 
(via .HX and/or .HZ) may cause overprinting. 


4.2.2.5 Marking Styles—Numerals and Concatenation 
-HM [arg]] ... [arg7] 


The registers named H/ through H7 are used as counters for the 
seven levels of headings. Their values are normally printed using 
Arabic numerals. The .HM macro (heading mark style) allows this 
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choice to be overridden, thus providing ‘‘outline’ and other docu- 
ment styles. This macro can have up to seven arguments; each argu- 
ment is a string indicating the type of marking to be used. Legal 
values and their meanings are shown below; omitted values are inter- 
preted as 1, while illegal values have no effect. 


Value Interpretation 
1 Arabic (default for all levels) 
0001 Arabic with enough leading zeroes to get 
the specified number of digits 
A Upper-case alphabetic 
a Lower-case alphabetic 
I Upper-case Roman 
i Lower-case Roman 


By default, the complete heading mark for a given level is built by 
concatenating the mark for that level to the right of all marks for all 
levels of higher value. To inhibit the concatenation of heading level 
marks, i.e., to obtain just the current level mark followed by a 
period, set the register Hr (heading-mark type) to 1. 


For example, a commonly-used “outline” style is obtained by: 


HMI Atai 
enr Ht 1 


4.3 Unnumbered Headings 


-HU heading-text 


-HU is a special case of .H; it is handled in the same way as .H, 
except that no heading mark is printed. In order to preserve the 
hierarchical structure of headings when .H and .HU calls are inter- 
mixed, each .HU heading is considered to exist at the level given by 
register Hu, whose initial value is 2. Thus, in the normal case, the 
only difference between: 


.HU heading-text 
and: 
.H 2 heading-text 


is the printing of the heading mark for the latter. Both have the 
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effect of incrementing the numbering counter for level 2, and reset- 
ting to zero the counters for levels 3 through 7. Typically, the value 
of Hu should be set to make unnumbered headings (if any) be the 
lowest-level headings in a document. 


.HU can be especially helpful in setting up appendices and other sec- 
tions that may not fit well into the numbering scheme of the main 
body of a document {14.2.1}. 


4.4 Headings and the Table of Contents 


The text of headings and their corresponding page numbers can be 
automatically collected for a table of contents. This is accomplished 
by doing the following two things: 


e specifying in the register C/ what level headings are to be saved 
e invoking the .TC macro {10.1} at the end of the document 


Any heading whose level is less than or equal to the value of the 
register C/ (contents level) is saved and later displayed in the table of 
contents. The default value for C/ is 2, i.e., the first two levels of 
headings are saved. 


Due to the way the headings are saved, it is possible to exceed the 
formatter’s storage capacity, particularly when saving many levels of 
many headings, while also processing displays {7} and footnotes 
{8}. If this happens, the “Out of temp file space’’ diagnostic 
{Appendix D} will be issued; the only remedy is to save fewer levels 
and/or to have fewer words in the heading text. 


4.5 First-Level Headings and Page Numbering Style 


By default, pages are numbered sequentially at the top of the page. 
For large documents, it may be desirable to use page numbering of 
the form “section-page,”’ where section is the number of the current 
first-level heading. This page numbering style can be achieved by 
specifying the ~rN3 or -rNS flag on the command line £9.93. As a 
side effect, this also has the effect of setting Ej to 1, i.e., each section 
begins on a new page. In this style, the page number is printed at the 
bottom of the page, so that the correct section number is printed. 
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4.6 User Exit Macros 


NOTE 


This section is intended only for users who are accustomed to 
writing formatter macros. 


-HX dlevel rlevel heading-text 
-HY dlevel rlevel heading-text 
.HZ dlevel rlevel heading-text 


The .HX, .HY, and .HZ macros are the means by which the user 
obtains a final level of control over the previously-described heading 
mechanism. MM does not define .HX, .HY, and .HZ; they are 
intended to be defined by the user. The .H macro invokes .HX 
shortly before the actual heading text is printed; it calls .HZ as its last 
action. After .HX is invoked, the size of the heading is calculated. 
This processing causes certain features that may have been included in 
-HX, such as .ti for temporary indent, to be lost. After the size cal- 
culation, .HY is invoked so that the user may respecify these 
features. All the default actions occur if these macros are not 
defined. If the .HX, .HY, or .HZ are defined by the user, the 
user-supplied definition is interpreted at the appropriate point. These 
macros can therefore influence the handling of all headings, because 
the .HU macro is actually a special case of the .H macro. 


If the user originally invoked the .H macro, then the derived level 
(dlevel) and the real level (rlevel) are both equal to the level given in 
the .H invocation. If the user originally invoked the .HU macro 
{4.3}, dlevel is equal to the contents of register Hu, and rlevel is 0. 
In both cases, heading-text is the text of the original invocation. 


By the time .H calls .HX, it has already incremented the heading 
counter of the specified level {4.2.2.5}, produced blank line(s) (vert- 
ical space) to precede the heading {4.2.2.1}, and accumulated the 
“heading mark’’, i.e., the string of digits, letters, and periods needed 
for a numbered heading. When .HX is called, all user-accessible 
registers and strings can be referenced, as well as the following: 


string }0 If rlevel is non-zero, this string contains the “heading 
mark.” Two unpaddable spaces (to separate the mark 
from the heading ) have been appended to this string. 
If rlevel is 0, this string is null. 
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register ;0 This register indicates the type of spacing that is to fol- 
low the heading {4.2.2.2}. A value of 0 means that 
the heading is run-in. A value of 1 means a break 
(but no blank line) is to follow the heading. A value 
of 2 means that a blank line (% a vertical space) is to 
follow the heading. 


string #2 _—‘If register ;0 is 0, this string contains two unpaddable 
spaces that will be used to separate the (run-in) head- 
ing from the following text. If register ;0 is non-zero, 
this string is null. 


register 33. This register contains an adjustment factor for a .ne 
request issued before the heading is actually printed. 
On entry to .HX, it has the value 3 if dlevel equals 1, 
and 1 otherwise. The .ne request is for the following 
number of lines: the contents of the register ;0 taken 
as blank lines (halves of vertical space) plus the con- 
tents of register ;3 as blank lines (halves of vertical 
space) plus the number of lines of the heading. 


The user may alter the values of }0, #2, and ;3 within .HX as 
desired. The following are examples of actions that might be per- 
formed by defining .HX to include the lines shown: 


Change first-level heading mark from format n. to n.0: 
wif \\$1=1 .ds }0 \\n(H1.0\0\0 (O stands for a space) 


Separate run-in heading from the text with a period and two 
unpaddable spaces: 
if \\n(;0=0 .ds }2 .\C\O 


Assure that at least 15 lines are left on the page before printing a 
first-level heading: 
wif \\$1=1 .nr 33 15-\\n(;0 


Add 3 additional blank lines before each first-level heading: 
wif \\S1=1 .sp 3 


Indent level 3 run-in headings by 5 spaces: 
wif \\$1=3 .ti Sn 


If temporary strings or macros are used within .HX, chose their 
names with care (14.1}. 


-HLY is called after the .ne is issued. Certain features requested in 
.HX must be repeated. For example: 
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.de HY 
wif \\$1=3 .ti 5n 


-HZ is called at the end of .H to permit user-controlled actions after 
the heading is produced. For example, in a large document, sections 
may correspond to chapters of a book, and the user may want to 
change a page header or footer, e.g.: 


.de HZ 
.if \\$1=1 .PF " ’’Section \\$3" " 


4.7 Hints for Large Documents 


A large document is often organized for convenience into one file per 
section. If the files are numbered, it is wise to use enough digits in 
the names of these files for the maximum number of sections, i.e., 
use suffix numbers 01 through 20 rather than 1 through 9 and 10 
through 20. 


Users often want to format individual sections of long documents. 
To do this with the correct section numbers, it is necessary to set 
register H/ to 1 less than the number of the section just before the 
corresponding “‘.H 1” call. For example, at the beginning of section 
5, insert: 


enr H1 4 


CAUTION 


This is a dangerous practice: it defeats the automatic 
(re)numbering of sections when sections are added or deleted. 
Remove such lines as soon as possible. 
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5. Lists 


This section describes many different kinds of lists: automatically- 
numbered and alphabetized lists, bullet lists, dash lists, lists with arbi- 
trary marks, and lists starting with arbitrary strings, e.g., with terms 
or phrases to be defined. 


5.1 Basic Approach 


In order to avoid repetitive typing of arguments to describe the 
appearance of items in a list, MM provides a convenient way to 
specify lists. All lists are composed of the following parts: 


e A list-initialization macro that controls the appearance of the 
list: line spacing, indentation, marking with special symbols, 
and numbering or alphabetizing. 


e One or more List trem (.LI) macros, each followed by the 
actual text of the corresponding list item. 


e The List End (,LE) macro that terminates the list and restores 
the previous indentation. 


Lists may be nested up to six levels. The list-initialization macro 
saves the previous list status (indentation, marking style, etc.); the 
.LE macro restores it. 


With this approach, the format of a list is specified only once at the 
beginning of that list. In addition, by building on the existing struc- 
ture, users may create their own customized sets of list macros with 
relatively little effort (5.4, Appendix A}. 


5.2 Sample Nested Lists 


The input for several lists and the corresponding output are shown 
below. The .AL and .DL macro calls {5.3.3} contained therein are 
examples of the /ist-initialization macros. This example will help us to 
explain the material in the following sections. Input text: 
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ALA 
LI 
This is an alphabetized item. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
AL 

LI 

This is a numbered item. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
DL 

LI 

This is a dash item. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
«LI + 1 
This is a dash item with a ‘‘plus’’ as prefix. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
.LE 

.LI 

This is numbered item 2. 

.LE 

LI 

This is another alphabetized item, B. 


This text shows the alignment of the second line of the item. 


The quick brown fox jumped over the lazy dog’s back. 
LE 
P 


This paragraph appears at the left margin. 
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Output: 


A. 


This is an alphabetized item. This text shows the alignment of 
the second line of the item. The quick brown fox jumped over 
the lazy dog’s back. 


1. This is a numbered item. This text shows the alignment 
of the second line of the item. The quick brown fox 
jumped over the lazy dog’s back. 


—— This is a dash item. This text shows the alignment of 
the second line of the item. The quick brown fox 
jumped over the lazy dog’s back. 


+ — This is a dash item with a ‘‘plus” as prefix. This text 
shows the alignment of the second line of the item. 
The quick brown fox jumped over the lazy dog’s back. 


2. This is numbered item 2. 


This is another alphabetized item, B. This text shows the align- 
ment of the second line of the item. The quick brown fox 
jumped over the lazy dog’s back. 


This paragraph appears at the left margin. 


5.3 Basic List Macros 


Because all lists share the same overall structure except for the list- 
initialization macro, we first discuss the macros common to all lists. 
Each list-initialization macro is covered in {5.3.3}. 


5.3.1 List Item 


-LI [mark] [1] 
one or more lines of text that make up the list item. 


The .LI macro is used with all lists. It normally causes the output of 
a single blank line (% a vertical space) before its item, although this 
may be suppressed. If no arguments are given, it labels its item with 
the current mark, which is specified by the most recent list- 
initialization macro. If a single argument is given to .LI, that argu- 
ment is output instead of the current mark. If two arguments are 
given, the first argument becomes a prefix to the current mark, thus 
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allowing the user to emphasize one or more items in a list. One 
unpaddable space is inserted between the prefix and the mark. For 
example: 


-BL 6 
LI 
This is a simple bullet item. 
LI + 
This replaces the bullet with a “‘plus.’’ 
-LI+1 
But this uses ‘‘plus’’ as prefix to the bullet. 
-LE 
yields: 
e This is a simple bullet item. 
+ This replaces the bullet with a ‘‘plus.”’ 


+ e But this uses ‘‘plus’’ as prefix to the bullet. 


CAUTION 


The mark must not contain ordinary (paddable) spaces, 
because alignment of items will be lost if the right margin is 


justified {3.3}. 


If the current mark (in the current list) is a null string, and the first 
argument of .LI is omitted or null, the resulting effect is that of a 
hanging indent, i.e., the first line of the following text is ‘‘out- 
dented,’ starting at the same place where the mark would have 
started {5.3.3.6}. 


5.3.2 List End 
.LE [1] 


List End restores the state of the list back to that existing just before 
the most recent list-initialization macro call. If the optional argument 
is given, the .LE outputs a blank line (% a vertical space). This 
option should generally be used only when the .LE is followed by 
running text, but not when followed by a macro that produces blank 
lines of its own, such as .P, .H, or .LI. 
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-H and .HU automatically clear all list information, so one may 
legally omit the .LE(s) that would normally occur just before either 
of these macros. Such a practice is not recommended, however, 
because errors will occur if the list text is separated from the heading 
at some later time (e.g., by insertion of text). 


5.3.3 List Initialization Macros 


The following are the various list-initialization macros. They are 
actually implemented as calls to the more basic .LB macro {5.4}. 


5.3.3.1 Automatically-Numbered or Alphabetized Lists 


.AL [type] [text-indent] [1] 


The .AL macro is used to begin sequentially-numbered or alphabet- 
ized lists. If there are no arguments, the list is numbered, and text ts 
indented Li, initially 6 (5) spaces from the indent in force when the 
.AL is called, thus leaving room for a space, two digits, a period, and 
two spaces before the text. 


Spacing at the beginning of the list and between the items can be 
suppressed by setting the Ls (list space) register. Ls is set to the 
innermost list level for which spacing is done. For example: 


-nr Ls 0 


specifies that no spacing will occur around any list items. The default 
value for Ls is 6 (which is the maximum list nesting level). 


The type argument may be given to obtain a different type of 
sequencing, and its value should indicate the first element in the 
sequence desired, i.e., it must be 1, A, a, I, ori {4.2.2.5}.° If rype 
is omitted or null, then “1” is assumed. If text-indent is non-null, it 


5. Values that specify indentation must be unscaled and are treated as ‘‘character 
positions,” i.e., as the number of ens. 
6. Note that the *‘0001"" format is not permitted. 
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is used as the number of spaces from the current indent to the text, 
i.e., it is used instead of Li for this list only. If text-indent is null, 
then the value of Zi will be used. 


If the third argument is given, a blank line (% a vertical space) will 
not separate the items in the list. A blank line (% a vertical space) 
will occur before the first item, however. 


5.3.3.2 Bullet List 


-BL [text-indent] [1} 
.BL begins a bullet list. in which each item is marked by a bullet (¢) 
followed by one space. If rext-indent is non-null, it overrides the 


default indentation—the amount of paragraph indentation as given in 
the register Pi (4.1}.’ 


If a second argument is specified, no blank lines will separate the 
items in the list. 


5.3.3.3 Dash List 


-DL [text-indent] [1] 


.DL is identical to .BL, except that a dash is used instead of a bullet. 


5.3.3.4 Marked List 
-ML mark [text-indent} | 1] 


-ML is much like .BL and .DL, but expects the user to specify an 
arbitrary mark, which may consist of more than a single character. 
Text is indented text-indent spaces if the second argument is not null; 
otherwise, the text is indented one more space than the width of 


7. So that, in the default case, the text of bullet and dash lists lines up with the 
first line of indented paragraphs. 
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mark. If the third argument is specified, no blank lines will separate 
the items in the list. 


CAUTION 


The mark must not contain ordinary (paddable) spaces, 
because alignment of items will be lost if the right margin is 
justified {3.3}. 


5.3.3.5 Reference List 
.RL [text-indent] [1] 


A .RL call begins an automatically-numbered list in which the 
numbers are enclosed by square brackets ([]). Texr-indent may be 
supplied, as for .AL. If omitted or null, it is assumed to be 6, a con- 
venient value for lists numbered up to 99. If the second argument is 
specified, no blank lines will separate the items in the list. 


5.3.3.6 Variable-ltem List 


. VL text-indent [mark-indent] [1] 


When a list begins with a .VL, there is effectively no current mark; it 
is expected that each .LI will provide its own mark. This form is typ- 
ically used to display definitions of terms or phrases. Mark-indent 
gives the number of spaces from the current indent to the beginning 
of the mark, and it defaults to 0 if omitted or null. Text-indent gives 
the distance from the current indent to the beginning of the text. If 
the third argument is specified, no blank lines will separate the items 
in the list. Here is an example of .VL usage: 
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— 


tr 7 

.VL 20 2 

-LI mark~1 

Here is a description of mark 1; 

“‘mark 1°’ of the .LI line contains a tilde translated 
to an unpaddable space in order 

to avoid extra spaces between 

‘mark’? and ‘‘1’* {3.3}. 

.LI second~ mark 

This is the second mark, also using a tilde translated 
to an unpaddable space. 

.LI third~ mark~longer~ than~ indent: 

This item shows the effect of a long mark; 

one space separates the mark 

from the text. 

.LI~ 

This item effectively has no mark because the 

tilde following the .LI is translated into a space. 


-LE 
yields: 
mark 1 Here is a description of mark 1; ‘“‘mark 1” of 
the .LI line contains a tilde translated to an 
unpaddable space in order to avoid extra 
spaces between “‘mark”’ and “1” £3.3}. 
second mark This is the second mark, also using a tilde 


translated to an unpaddable space. 


third mark longer than indent: This item shows the effect of a long 
mark; one space separates the mark from the 
text. 


This item effectively has no mark because the 
tilde following the .LI is translated into a 
space. 


The tilde argument on the last .LI above is required; otherwise a 
hanging indent would have been produced. A hanging indent is pro- 
duced by using .VL and calling .LI with no arguments or with a null 
first argument. For example: 
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.VL 10 

LI 

Here is some text to show a hanging indent. 
The first line of text is at the left margin. 
The second is indented 10 spaces. 

LE 


yields: 


Here is some text to show a hanging indent. The first line of text is 
at the left margin. The second is indented 10 spaces. 


CAUTION 


The mark must not contain ordinary (paddable) spaces, 
because alignment of items will be lost if the right margin is 
justified {3.3}. 


5.4 List-Begin Macro and Customized Lists 
.LB text-indent mark-indent pad type [mark] [LI-space] [LB-space] 


The list-initialization macros described above suffice for almost all 
cases. However, if necessary, one may obtain more control over the 
layout of lists by using the basic list-begin macro .LB, which is also 
used by all the other list-initialization macros. Its arguments are as 
follows: 


Text-indent gives the number of spaces that the text is to be indented 
from the current indent. Normally, this value is taken from the regis- 
ter Li for automatic lists and from the register Pi for bullet and dash 
lists. 


The combination of mark-indent and pad determines the placement of 
the mark, The mark is placed within an area (called mark area) that 
starts mark-indent spaces to the right of the current indent, and ends 
where the text begins (i.e., ends rext-indent spaces to the right of the 
current indent).® Within the mark area, the mark is /eft-justified if 
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pad is 0. If pad is greater than 0, say n, then n blanks are appended 
to the mark; the mark-indent value is ignored. The resulting string 
immediately precedes the text. That is, the mark is effectively right- 
justified pad spaces immediately to the left of the text. 


Type and mark interact to control the type of marking used. If type is 
0, simple marking is performed using the mark character(s) found in 
the mark argument. If type is greater than 0, automatic numbering or 
alphabetizing is done, and mark is then interpreted as the first item in 
the sequence to be used for numbering or alphabetizing, 1.e., it is 
chosen from the set (1, A, a, I, i) as in {5.3.3.1}. That is: 


Type Mark Result 


0 omitted hanging indent 

0 string String is the mark 

>0 omitted arabic numbering 

>0 one of: automatic numbering or 


1, A, a, I, i alphabetic sequencin 


Each non-zero value of type from 1 to 6 selects a different way of 
displaying the marks. The following table shows the output appear- 
ance for each value of rype: 


where x is the generated number or letter. 


8. The mark-indent argument is typically 0. 
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CAUTION 


The mark must not contain ordinary (paddable) spaces, 
because alignment of items will be lost if the right margin is 
justified {3.3}. 


Ll-space gives the number of blank lines (halves of a vertical space) 
that should be output by each .LI macro in the list. If omitted, L/- 
space defaults to 1; the value 0 can be used to obtain compact lists. If 
Ll-space is greater than 0, the .LI macro issues a .ne request for two 
lines just before printing the mark. 


LB-space, the number of blank lines (% a vertical space) to be output 
by .LB itself, defaults to 0 if omitted. 


There are three reasonable combinations of Li-space and LB-space. 
The normal case is to set L/-space to 1 and LB-space to 0, yielding 
one blank line before each item in the list; such a list is usually ter- 
minated with a ‘“‘.LE 1” to end the list with a blank line. In the 
second case, for a more compact list, set L/-space to 0 and LB-space 
to 1, and, again, use ‘‘.LE 1” at the end of the list. The result is a 
list with one blank line before and after it. If you set both L/-space 
and LB-space to 0, and use ‘“‘.LE” to end the list, a list without any 
blank lines will result. 


Appendix A shows how one can build upon the supplied list macros 
to obtain other kinds of lists. 


6. Memorandum and Released Paper Styles 


One use of MM is for the preparation of memoranda and released 
papers, which have special requirements for the first page and for the 
cover sheet. The information needed for the memorandum or 
released paper (title, author, date, case numbers, etc.) is entered in 
the same way for both styles; an argument to one macro indicates 
which style is being used. The following sections describe the macros 
used to provide this data. The required order is shown in {6.9}. 


If neither the memorandum nor released-paper style is desired, the 
macros described below should be omitted from the input text. If 
these macros are omitted, the first page will simply have the page 
header {9} followed by the body of the document. 
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6.1 Title 


-TL [charging-case] [filing-case] 
one or more lines of title text 


The arguments to the .TL macro are the charging case number(s) and 
filing case number(s).? The title of the memorandum or paper fol- 
lows the .TL macro and is processed in fill mode {3.1}. Multiple 
charging case numbers are entered as ‘‘sub-arguments’’ by separating 
each from the previous with a comma and a space, and enclosing the 
entire argument within double quotes. Multiple filing case numbers 
are entered similarly. For example: 


-TL "12345, 67890" 987654321 
On the Construction of a Table of All Even Prime Numbers 


The .br request may be used to break the title on output into several 
lines as follows: 


-TL 12345 

First Title Line 
.br 

\t. br 

Second Title Line 


On output, the title appears after the word ‘‘subject’” in the 
memorandum style. In the released-paper style, the title is centered 
and bold. 


If only a charging case number or only a filing case number is given, 
then it will be separated from the title in the memorandum style by a 
dash and will appear on the same line as the title. If both case 
numbers are given and are the same, then “Charging and Filing 
Case” followed by the number will appear on a line following the 
title. If the two case numbers are different, then separate lines for 
“Charging Case”’ and ‘‘File Case” will appear after the title. 


9. The “charging case” is the case number to which time was charged for the 
development of the project described in the memorandum. The ‘“‘filing case’’ 
is a number under which the memorandum is to be filed. 
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6.2 Author(s) 


-AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] [arg] 
AT [title] ... 


The .AU macro receives as arguments information that describes an 
author. If any argument contains blanks, it must be enclosed within 
double quotes. The first six arguments must appear in the order 
given (a separate .AU macro is required for each author). 


The .AT macro is used to specify the author’s title. Up to nine argu- 
ments may be given. Each will appear in the Signature Block for 
memorandum style {6.11.1} on a separate line following the signer’s 
name. The .AT must immediately follow the .AU for the given 
author. For example: 


AU "J. J. Jones" JJJ PY 9876 5432 1Z-234 
.AT Director "Materials Research Laboratory" 


In the “‘from’’ portion in the memorandum style, the author’s name is 
followed by location and department number on one line and by 
room number and extension number on the next. The ‘“‘x’’ for the 
extension is added automatically. The printing of the location, 
department number, extension number, and room number may be 
suppressed on the first page of a memorandum by setting the register 
Au to 0; the default value for Au is 1. Arguments 7 through 9 of the 
-AU macro, if present, will follow this ‘normal’ author information 
in the ‘‘from’’ portion, each on a separate line. These last three argu- 
ments may be used for organizational numbering schemes, etc. For 
example: 


AU "S. P. Lename" SPL IH 9988 7766 SH-444 9876-543210.01MF 


The name, initials, location, and department are also used in the Sig- 
nature Block {6.11.1}. The author information in the “from” por- 
tion, as well as the names and initials in the Signature Block will 
appear in the same order as the .AU macros. 


The names of the authors in the released-paper style are centered 
below the title. After the name of the last author, ‘‘Bell Labora- 
tories’? and the location are centered. For the case of authors from 
different locations, see {6.8}. 
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6.3 TM Number(s) 


-TM [number]... 


If the memorandum is a Technical Memorandum, the TM numbers 
are supplied via the .TM macro. Up to nine numbers may be speci- 
fied. Example: 


«TM 7654321 77777777 


This macro call is ignored in the released-paper and external-letter 
styles {6.6}. 


6.4 Abstract 


-AS [arg] [indent] 
text of the abstract 
AE 


The .AS (abstract start) and .AE (abstract end) macros bracket the 
(optional) abstract. Abstracts are printed on page 1 of a document 
and/or on its cover sheet. !° 


In a released paper (first argument of the .MT macro is 4; see {6.6}) 
and in a Technical Memorandum, if the first argument of .AS is 0, 
the abstract will be printed on page 1 and on the cover sheet (if any); 
if the first argument of .AS is 1, the abstract will appear on/y on the 
cover sheet (if any). 


In Memoranda for File and in all other documents (other than exter- 
nal letters), if the first argument of .AS is 0, the abstract will appear 
on page 1 and there will be no cover sheet printed; if the first argu- 
ment of .AS is 2, the abstract will appear on/y on the cover sheet, 
which will be produced automatically in this case (1.e., without invok- 
ing the .CS macro). It is not possible to get either an abstract or a 


10. There are three styles of cover sheet: released paper, Technical Memorandum, 
and Memorandum for File {10.2}: the last one of these is also used for 
Engineer’s Notes, Memoranda for Record, etc. Cover sheets for released 
papers and Technical Memoranda are obtained by invoking the .CS macro 


{10.2}. 
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cover sheet with an external letter (first argument of the .MT macro 


is S). 


Notations {6.11.2} such as a ‘‘copy to” list are allowed on Memoran- 
dum for File cover sheets; the .NS and .NE macros must appear after 
the .AS 2 and .AE. Headings (4.2, 4.3} and displays {7} are not 
permitted within an abstract. 


The abstract is printed with ordinary text margins; an indentation to 
be used for both margins can be specified as the second argument of 
ASS! 


6.5 Other Keywords 


-OK [keyword] ... 
Topical keywords should be specified on a Technical Memorandum 
cover sheet. Up to nine such keywords or keyword phrases may be 


specified as arguments to the .OK macro; if any keyword contains 
spaces, it must be enclosed within double quotes. 


6.6 Memorandum Types 


.MT [type] [addressee] 
The .MT macro controls the format of the top part of the first page 


of a memorandum or of a released paper, as well as the format of the 
cover sheets. Legal codes for type and the corresponding values are: 


11. Values that specify indentation must be unscaled and are treated as ‘‘character 
positions,’’ i.e., as the number of ens. 
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Code Value 
ve no memorandum type printed 
0 no memorandum type printed 

none MEMORANDUM FOR FILE 
1 MEMORANDUM FOR FILE 
2 PROGRAMMER’S NOTES 
3 ENGINEER’S NOTES 
4 released-paper style 
5 external-letter style 

" string" String: 


If rype indicates a memorandum style, then value will be printed after 
the last line of author information. If type is longer than one charac- 
ter, then the string, itself, will be printed. For example: 


-MT "Technical Note #5" 


A simple letter is produced by calling .MT with a null (but nor omit- 
ted!) or zero argument. 


The second argument to .MT is the name of the addressee of a letter; 
if present, that name and the page number replace the normal page 
header on the second and following pages of a letter: 


-MT 1 "John Jones" 
produces 
John Jones — 2 


This second argument may nor be used for this purpose if the first 


argument is 4 (i.e., for the released-paper style) as explained in 
6.8}. 


In the external-letter style (MT 5), only the title (without the word 
“subject:”) and the date are printed in the upper left and right 
corners, respectively, on the first page. It is expected that preprinted 
stationery will be used, providing the author’s company logo and 
address. 
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6.7 Date and Format Changes 
6.7.1 Changing the Date 


By default, the current date appears in the “‘date’” part of a 
memorandum. This can be overridden by using: 


.ND new-date 


The .ND macro alters the value of the string DT, which is initially set 
to the current date. 


6.7.2 Alternate First-Page Format. 


One can specify that the words ‘‘subject,”’ “date,” and ‘from’ (in the 
memorandum style) be omitted and that an alternate company name 
be used: 


.AF [company-name] 


If an argument is given, it replaces ‘Bell Laboratories”, without 
affecting the other headings. If the argument is null, “Bell Labora- 
tories” is suppressed; in this case, extra blank lines are inserted to 
allow room for stamping the document with a Bell System logo or a 
Bell Laboratories stamp. .AF with no argument suppresses ‘‘Bell 
Laboratories” and the ‘“‘Subject/Date/From”’ headings, thus allowing 
output on preprinted stationery. The use of .AF with no arguments 
is equivalent to the use of -rAl {2.4}, except that the latter must be 
used if it is necessary to change the line length and/or page offset 
(which default to 5.8i and li, respectively, for preprinted forms). 
The command line options -rOk and -rWk {2.4} are not effective 
with .AF. The only .AF use appropriate for rroff is to specify a 
replacement for ‘‘Bell Laboratories”. 


The command line option -rEn {2.4} controls the font of the 
“Subject/Date/From”’ block. 
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6.8 Released-Paper Style 


The released-paper style is obtained by specifying: 
.MT 4 [1] 


This results in a centered, bold title followed by centered names of 
authors. The location of the last author is used as the location fol- 
lowing ‘‘Bell Laboratories” (unless .AF {6.7.2} specifies a different 
company). If the optional second argument to .MT 4 is given, then 
the name of each author is followed by the respective company name 
and location. 


Information necessary for the memorandum style but not for the 
released-paper style is ignored. 


If the released-paper style is utilized, most BTL location codes!* are 
defined as strings that are the addresses of the corresponding BTL 
locations. These codes are needed only until the .MT macro is 
invoked. Thus, following the .MT macro, the user may re-use these 
string names. In addition, the macros described in {6.11} and their 
associated lines of input are ignored when the released-paper style is 
specified. 


Authors from non-BTL locations may include their affiliations in the 
released-paper style by specifying the appropriate .AF and defining a 
string (with a 2 character name such as XX) for the address before 
each .AU. For example: 


.TL 

A Learned Treatise 

.AF "Getem Inc." 

.ds XX "22 Maple Avenue, Sometown 09999" 
.AU "F. Swatter" "" XX 

.AF "Bell Laboratories" 

-AU "Sam P. Lename" "" CB 

MT 41 


12. Currently, the complete list is: AK, AL, ALF, CB, CH, CP, DR, FJ, HL, 
HO, HOH, HP, IH, IN, INH, IW, MH, MV, PY, RD, RR, WB, WH, and 
WV. 
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6.9 Order of Invocation of “Beginning” Macros 


The macros described in {6.1-6.7}, if present, must be given in the 
following order: 


.ND new-date 

-TL [charging-case] [filing-case] 
one or more lines of text 

.AF [company-name] 

.AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] [arg] 
.AT [title] ... 

.TM [number] ... 

.AS [arg] [indent] 

one or more lines of text 

AE 

NS [arg] 

one or more lines of text 

.NE 

-OK [keyword] ... 

.MT [type] [addressee] 


The only required macros for a memorandum or a released paper are 
.TL, .AU, and .MT; all the others (and their associated input lines) 
may be omitted if the features they provide are not needed. Once 
.MT has been invoked, none of the above macros (except .NS and 
.NE) can be re-invoked because they are removed from the table of 
defined macros to save space. 


6.10 Example 


The input text for this manual begins as follows: 


.TL 

MM\*(EMMemorandum Macros 

-AU "D. W. Smith" DWS PY 

AU "J. R. Mashey" JRM PY 

.AU "E. C. Pariser (January 1980 Revision)" ECP PY 
.AU "N. W. Smith (June 1980 Revision)" NWS PY 
.MT 4 
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Appendix C shows the input and both nroff and troff outputs for a 
simple letter. 


6.11 Macros for the End of a Memorandum 


At the end of a memorandum (but nor of a released paper), the sig- 
natures of the authors and a list of notations'* can be requested. The 
following macros and their input are ignored if the released-paper 
style is selected. 


6.11.1 Signature Block 


-FC [closing] 
SG [arg] [1] 


.FC prints ‘Yours very truly,” as a formal closing. It must be given 
before the .SG which prints the signer’s name. A different closing 
may be specified as an argument to .FC. 


.SG prints the author name(s) after the formal closing, if any. Each 
name begins at the center of the page. Three blank lines are left 
above each name for the actual signature. If no arguments are given, 
the line of reference data!* will not appear. A non-null first argu- 
ment is treated as the typist’s initials, and is appended to the refer- 
ence data. Supply a null first argument to print the reference data 
with neither the typist’s initials nor the preceding hyphen. 


If there are several authors and if the second argument is given, then 
the reference data is placed on the same line as the name of the first, 
rather than last, author. 


The reference data contains only the location and department number 
of the first author. Thus, if there are authors from different depart- 
ments and/or from different locations, the reference data should be 


13. See the BTL Office Guide'*!, pp. 1.12-16. 

14. The following information is known as reference data: location code, 
department number, author’s initials, and typist’s initials, all separated by 
hyphens. See the BTL Office Guide'”!, page 1.11. 
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supplied manually after the invocation (without arguments) of the 
.SG macro. For example: 


SG 

.TS 

“sp —lv 
PY/MH-9876/5432-JJJ/SPL-cen 


6.11.2 “Copy to” and Other Notations 


NS [arg] 
zero or more lines of the notation 
.NE 


After the signature and reference data, many types of notations may 
follow, such as a list of attachments or “‘copy to”’ lists. The various 
notations are obtained through the .NS macro, which provides for the 
proper spacing and for breaking the notations across pages, if neces- 
sary. 


The codes for arg and the corresponding notations are: 


Code Notations 
none Copy to 
"tt Copy to 
0 Copy to 
1 Copy (with att.) to 
2 Copy (without att.) to 
3 Att. 
4 Atts. 
5 Enc. 
6 Encs. 
7 Under Separate Cover 
8 Letter to 
9 Memorandum to 
"string" Copy (string) to 


If arg consists of more than one character, it is placed within 
parentheses between the words ‘‘Copy” and ‘‘to.”” For example: 
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-NS "with att. 1 only" 


will generate ‘“‘Copy (with att. 1 only) to” as the notation. More than 
one notation may be specified before the .NE occurs, because a .NS 
macro terminates the preceding notation, if any. For example: 


-NS 4 

Attachment 1-List of register names 
Attachment 2-List of string and macro names 
«NS 1 

J. J. Jones 

.NS 2 

S. P. Lename 

G. H. Hurtz 

.NE 


would be formatted as: 


Atts. 
Attachment 1-List of register names 
Attachment 2-List of string and macro names 


Copy (with att.) to 
J. J. Jones 


Copy (without att.) to 
S. P. Lename 
G. H. Hurtz 


The .NS and .NE macros may also be used at the beginning following 
.AS 2 and .AE to place the notation list on the Memorandum for 
File cover sheet {6.4}. If notations are given at the beginning 
without .AS 2, they will be saved and output at the end of the docu- 
ment. 


6.11.3 Approval Signature Line 


.AV approver’s-name 


The .AV macro may be used after the last notation block to automat- 
ically generate a line with spaces for the approval signature and date. 
For example, 


-AV "Jane Doe" 


produces: 
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APPROVED: 


Jane Doe Date 


6.12 Forcing a One-Page Letter 


At times, one would like just a bit more space on the page, forcing 
the signature or items within notations onto the bottom of the page, 
so that the letter or memo is just one page in length. This can be 
accomplished by increasing the page length through the —-rLn option, 
e.g. -rL90. This has the effect of making the formatter believe that 
the page is 90 lines long and therefore giving it more room than usual 
to place the signature or the notations. This will only work for a 
single-page letter or memo. 


7. Displays 


Displays are blocks of text that are to be kept together—not split 
across pages. MM provides two styles of displays: > a static (.DS) 
style and a floating (.DF) style. In the sratic style, the display 
appears in the same relative position in the output text as it does in 
the input text; this may result in extra white space at the bottom of 
the page if the display is too big to fit there. In the floating style, the 
display ‘‘floats’” through the input text to the top of the next page if 
there is not enough room for it on the current page; thus the input 
text that follows a floating display may precede it in the output text. 
A queue of floating displays is maintained so that their relative order 
is not disturbed. 


By default, a display is processed in no-fill mode, with single-spacing, 
and is not indented from the existing margins. The user can specify 
indentation or centering, as well as fill-mode processing. 


15. Displays are processed in an environment that is different from that of the body 
of the text (see the .ev request!?l), 
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Displays and footnotes {8} may never be nested, in any combination 
whatsoever. Although lists {5} and paragraphs {4.1} are permitted, 
no headings (.H or .HU) {4.2, 4.3} can occur within displays or 
footnotes. 


7.1 Static Displays 


-DS [format] [fill] [rindent] 
one or more lines of text 
.DE 


A static display is started by the .DS macro and terminated by the 
-DE macro. With no arguments, .DS will accept the lines of text 
exactly as they are typed (no-till mode) and will nor indent them from 
the prevailing left margin indentation or from the right margin. The 
rindent argument is the number of characters!® that the line length 
should be decreased, i.e., an indentation from the right margin. 


The format argument to .DS is an integer or letter used to control the 
left margin indentation and centering with the following meanings: 


| Format _ Meaning 

[wn no indent | 

| OorLl no indent | 

i 1lorl indent by standard amount | 
2orC center each line 


3 or CB — center as a block 


as 4 


The fill argument is also an integer or letter and can have the follow- 
ing meanings: 


Fill __ Meaning 


yest no-fill mode 
Qcr N no-fill mode 
|lorF __ fill mode | 


Omitted arguments are taken to be zero. 


16. This number must be unscaled in nroff and is treated as ens. It may be scaled 
in troff or else defaults to ems. 
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The standard amount of indentation is taken from the register Si, 
which is initially 5. Thus, by default, the text of an indented display 
aligns with the first line of indented paragraphs, whose indent is con- 
tained in the Pi register 4.1}. Even though their initial values are 
the same, these two registers are independent of one another. 


The display format value 3 (CB) centers the entire display as a block 
(as opposed to .DS 2 and .DF 2, which center each line individu- 
ally). That is, all the collected lines are left-justified, and then the 
display is centered, based on the width of the longest line. This for- 
mat must be used in order for the egn/neqn ‘‘mark’’ and ‘“‘lineup”’ 
feature to work with centered equations (see section 7.4 below). 


By default, a blank line (% a vertical space) is placed before and after 
static and floating displays. These blank lines before and after static 
displays can be inhibited by setting the register Ds to 0. 


The following example shows the usage of all three arguments for 
displays. This block of text will be filled and indented 5 spaces from 
both the left and the right margins (i.e., centered). 


.DSIFS5 

‘“‘We the people of the United States, in order to form 
a more perfect union, establish justice, ensure domes- 
tic tranquility, provide for the common defense, and 
secure the blessings of liberty to ourselves and our pos- 
terity, do ordain and establish this Constitution to the 
United States of America.” 

.DE 


7.2 Floating Displays 


.DF [format] [fill] [rindent] 
one or more lines of text 
.DE 


A floating display is started by the .DF macro and terminated by the 
.DE macro. The arguments have the same meanings as for .DS 
{7.1}, except that, for floating displays, indent, no indent, and 
centering are always calculated with respect to the initial left margin, 
because the prevailing indent may change between the time when the 
formatter first reads the floating display and the time that the display 
is printed. One blank line (% a vertical space) always occurs both 
before and after a floating display. 
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The user may exercise great control over the output positioning of 
floating displays through the use of two number registers, De and Df. 
When a floating display is encountered by nroff or troff, it is pro- 
cessed and placed onto a queue of displays waiting to be output. 
Displays are always removed from the queue and printed in the order 
that they were entered on the queue, which is the order that they 
appeared in the input file. If a new floating display is encountered 
and the queue of displays is empty, then the new display is a candi- 
date for immediate output on the current page. Immediate output is 
governed by the size of the display and the setting of the Df register 
(see below). The De register (see below) controls whether or not text 
will appear on the current page after a floating display has been pro- 
duced. 


As long as the queue contains one or more displays, new displays will 
be automatically entered there, rather than being output. When a 
new page is started (or the top of the second column when in two- 
column mode) the next display from the queue becomes a candidate 
for output if the Df register has specified “top-of-page’ output. 
When a display is output it is also removed from the queue. 


When the end of a section (when using section-page numbering) or 
the end of a document is reached, all displays are automatically 
removed from the queue and output. This will occur before a .SG, 
.CS, or .TC is processed. 


A display is said to “fit on the current page” if there is enough room 
to contain the entire display on the page, or if the display is longer 
than one page in length and less than half of the current page has 
been used. Also note that a wide (full page width) display will never 
fit in the second column of a two-column document. 


The registers, their settings, and their effects are as follows: 


De Action 
DEFAULT: No special action occurs. 

1 A page eject will always follow the output of each floating 
display, so only one floating display will appear on a page and 
no text will follow it. 


NOTE: For any other value, the action performed is the 
same as for the value 1. 
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Df Action 

0 Floating displays will not be output until end of section (when 
section-page numbering) or end of document. 

1 Output the new floating display on the current page if there is 
room, otherwise hold it until the end of the section or docu- 
ment. 

2 Output exactly one floating display from the queue at the top 
of a new page or column (when in two-column mode). 

3 Output one floating display on current page if there is room. 
Output exactly one floating display at the top of a new page or 
column. 

4 Output as many displays as will fit (at least one), starting at 
the top of a new page or column. Note that if register De is 
set to 1, each display will be followed by a page eject, causing 
a new top of page to be reached where at least one more 
display will be output. (This also applies to value 5, below.) 

5 DEFAULT: Output a new floating display on the current page 
if there is room. Output at least one, but as many displays as 
will fit starting at the top of a new page or column. 


NOTE: For any value greater than 5, the action per- 
formed is the same as for the value 5. 


The .WC macro {12.4} may also be used to control handling of 
displays in double-column mode and to control the break in the text 
before floating displays. 


7.3 Tables 


TS [H] 

global options; 
column descriptors. 
title lines 

[.TH [N]] 

data within the table. 
TE 


The .TS (table start) and .TE (table end) macros make possible the 
use of the rb/(1) processor!7], They are used to delimit the text to be 
examined by rb/(1) as well as to set proper spacing around the table. 
The display function and the rb/(1) delimiting function are indepen- 
dent of one another, however, so in order to permit one to keep 
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together blocks that contain any mixture of tables, equations, filled 
and unfilled text, and caption lines the .TS/.TE block should be 
enclosed within a display (.DS/.DE). Floating tables may be 
enclosed inside floating displays (, DF/.DE). 


The macros .TS and .TE also permit the processing of tables that 
extend over several pages. If a table heading is needed for each page 
of a multi-page table, specify the argument ‘‘H” to the .TS macro as 
above. Following the options and format information, the table 
heading is typed on as many lines as required and followed by the 
-TH macro. The .TH macro must occur when “.TS H” is used. 
Note that this is nor a feature of rb/(1), but of the macro definitions 
provided by MM. 


The table header macro .TH may take as an argument the letter N. 
This argument causes the table header to be printed only if it is the 
first table header on the page. This option is used when it is neces- 
sary to build long tables from smaller .TS H/.TE segments. For 
example: 


TS H 

global options; 
column descriptors. 
Title lines 

.TH 

data 

TE 

TSH 

global options; 
column descriptors. 
Title lines 

-THN 

data 

TE 


will cause the table heading to appear at the top of the first table seg- 
ment, and no heading to appear at the top of the second segment 
when both appear on the same page. However, the heading will still 
appear at the top of each page that the table continues onto. This 
feature is used when a single table must be broken into segments 
because of table complexity (for example, too many blocks of filled 
text). If each segment had its own .TS H/.TH sequence, each seg- 
ment would have its own header. However, if each table segment 
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after the first uses .TS H/.THN then the table header will only 
appear at the beginning of the table and the top of each new page or 
column that the table continues onto. 


For nroff, the -e option (-E for mm(1) {2.1}) may be used for ter- 
minals, such as the 450, that are capable of finer printing resolution. 
This will cause better alignment of features such as the lines forming 
the corner of a box. Note that —-e is not effective with col (1). 


7.4 Equations 


.DS 
.EQ [label] 
equation(s) 
.EN 
.DE 


The equation setters eqn(1) and negn6l expect to use the .EQ (equa- 
tion start) and .EN (equation end) macros as delimiters in the same 
way that rb/(1) uses .TS and .TE; however, .EQ and .EN must occur 
inside a .DS/.DE pair. 


NOTE 


There is an exception to this rule: if .EQ and .EN are used 
only to specify the delimiters for in-line equations or to specify 
eqn/neqn “defines,” .DS and .DE must nor be used; otherwise 
extra blank lines will appear in the output. 


The .EQ macro takes an argument that will be used as a label for the 
equation. By default, the label will appear at the right margin in the 
“vertical center’? of the general equation. The Eq register may be set 
to 1 to change the labeling to the left margin. 


The equation will be centered for centered displays; otherwise the 
equation will be adjusted to the opposite margin from the label. 
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7.5 Figure, Table, Equation, and Exhibit Captions 


.FG [title] [override] [flag] 
-TB [title] [override] [flag] 
iS [title] [override] [flag] 

X [title] [override] [flag] 


The .FG (Figure Title), .TB (Table Title), .EC (Equation Caption) 
and .EX (Exhibit Caption) macros are normally used inside .DS/.DE 
pairs to automatically number and title figures, tables, and equations. 
They use registers Fg, Tb, Ec, and Ex, respectively (see {2.4} on 
-rN5 to reset counters in sections). As an example, the call: 


-FG "This is an illustration" 
yields: 


Figure 1. This is an illustration 


-TB replaces “Figure” by “TABLE”; .EC replaces ‘Figure’? by 
‘Equation’, and .EX replaces ‘‘Figure’ by ‘‘Exhibit’’. Output is 
centered if it can fit on a single line; otherwise, all lines but the first 
are indented to line up with the first character of the title. The for- 
mat of the numbers may be changed using the .af request of the for- 
matter. The format of the caption may be changed from 
“Figure 1. Title’ to “Figure 1 - Title’? by setting the Of register to 1. 


The override string is used to modify the normal numbering. If flag 
is omitted or 0, override is used as a prefix to the number; if flag is 1, 
override is used as a suffix; and if flag is 2, override replaces the 
number. If ~rN5 {2.4} is given, “‘section-figure’’ numbering is set 
automatically and user-specified override string is ignored. 


As a matter of style, table headings are usually placed ahead of the 
text of the tables, while figure, equation, and exhibit captions usually 
occur after the corresponding figures and equations. 
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7.6 List of Figures, Tables, Equations, and Exhibits 


A List of Figures, List of Tables, List of Exhibits, and List of Equa- 
tions may be obtained. They will be printed after the Table of Con- 
tents is printed if the number registers Lf, Lr, Lx, and Le (respec- 
tively) are set to 1. Lf, Lr, and Lx are 1 by default, Le is 0 by 
default. 


The titles of these Lists may be changed by redefining the following 
strings which are shown here with their default values: 


.ds Lf LIST OF FIGURES 

.ds Lt LIST OF TABLES 

.ds Lx LIST OF EXHIBITS 
.ds Le LIST OF EQUATIONS 


8. Footnotes 


There are two macros that delimit the text of footnotes,'” a string 
used to automatically number the footnotes, and a macro that speci- 
fies the style of the footnote text. 


8.1 Automatic Numbering of Footnotes 


Footnotes may be automatically numbered by typing the three charac- 
ters “\*F”’ (i.e., invoking the string F) immediately after the text to 
be footnoted, without any intervening spaces. This will place the next 
sequential footnote number (in a smaller point size) a half-line above 
the text to be footnoted. 


17. Footnotes are processed in an environment that is different from that of the 
body of the text (see the .ev request!?1). 
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8.2 Delimiting Footnote Text 


There are two macros that delimit the text of each footnote: 


FS [label] 
one or more lines of footnote text 
.FE 


The .FS (footnote start) marks the beginning of the text of the foot- 
note, and the .FE marks its end. The /abel on the .FS, if present, 
will be used to mark the footnote text. Otherwise, the number 
retrieved from the string F will be used. Note that automatically- 
numbered and user-labeled footnotes may be intermixed. If a foot- 
note is labeled (.FS label), the text to be footnoted must be followed 
by label, rather than by ‘““\*F”. The text between .FS and .FE is 
processed in fill mode. Another .FS, a .DS, or a .DF are not permit- 
ted between the .FS and .FE macros. Automatically numbered foot- 
notes may not be used for information, such as the title and abstract, 
to be placed on the cover sheet, but labeled footnotes are allowed. 
Similarly, only labeled footnotes may be used with tables {7.3}. 
Examples: 


1. Automatically-numbered footnote: 


This is the line containing the word\*F 
LFS 

This is the text of the footnote. 

FE 

to be footnoted. 


2. Labelled footnote: 


This is a labeled* 

«FS * 

The footnote is labeled with an asterisk. 
»FE 

footnote. 


The text of the footnote (enclosed within the .FS/.FE pair) should 
immediately follow the word to be footnoted in the input text, so that 
“\*F” or label occurs at the end of a line of input and the next line 
is the .FS macro call. It is also good practice to append a unpaddable 
space {3.3} to “\*F” or label when they follow an end-of-sentence 
punctuation mark (i.e., period, question mark, exclamation point). 
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Appendix B illustrates the various available footnote styles as well as 
numbered and labeled footnotes. 


8.3 Format of Footnote Text 


-FD [arg] [1] 


Within the footnote text, the user can control the formatting style by 
specifying text hyphenation, right margin justification, and text inden- 
tation, as well as left- or right-justification of the label when text 
indenting is used. The .FD macro is invoked to select the appropri- 
ate style. The first argument is a number from the left column of the 
following table. The formatting style for each number is given by the 
remaining four columns. For further explanation of the first two of 
these columns, see the definitions of the .ad, .hy, .na, and .nh 
requests|”]. 


arg Hyphenation _Adjust Text Indent Label Justification 


0  .nh .ad text indent label left justified 
1 shy .ad " s 
2 .nh na " " 
3 -hy na ¥ " 
4 .nh ad no text indent x 
5 hy wad 7 " 
6 .nh na " y 
7 ehy .na a iy 
8 nh ead text indent label right justified 
9 hy .ad * 
10 -nh na " " 
11 «hy na " ” 


If the first argument to .FD is out of range, the effect is as if .FD 0 
were specified. If the first argument is omitted or null, the effect is 
equivalent to .FD 10 in nroff and to .FD 0 in troff; these are also the 
respective initial defaults. 


If a second argument is specified, then whenever a first-level heading 
is encountered, automatically-numbered footnotes begin again with 1. 
This is most useful with the ‘‘section-page’’ page numbering scheme. 
As an example, the input line: 


FD" 1 
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maintains the default formatting style and causes footnotes to be 
numbered afresh after each first-level heading. 


For long footnotes that continue onto the following page, it is possible 
that, if hyphenation is permitted, the last line of the footnote on the 
current page will be hyphenated. Except for this case (over which the 
user has control by specifying an even argument to .FD), hyphenation 
across pages is inhibited by MM. 


Footnotes are separated from the body of the text by a short rule. 
Footnotes that continue to the next page are separated from the body 
of the text by a full-width rule. In sroff, footnotes are set in type that 
is two points smaller than the point size used in the body of the text. 


8.4 Spacing between Footnote Entries 


Normally, one blank line (a three-point vertical space) separates the 
footnotes when more than one occurs on a page. To change this 
spacing, set the register Fs to the desired value. For example: 


enor Fs 2 


will cause two blank lines (a six-point vertical space) to occur between 
footnotes. 


9. Page Headers and Footers 


Text that occurs at the top of each page is known as the page header. 
Text printed at the bottom of each page is called the page footer. 
There can be up to three lines of text associated with the header: 
every page, even page only, and odd page only. Thus the page 
header may have up to two lines of text: the line that occurs at the 
top of every page and the line for the even- or odd-numbered page. 
The same is true for the page footer. 


This section first describes the default appearance of page headers and 
page footers, and then the ways of changing them. We use the term 
header (not qualified by even or odd) to mean the line of the page 
header that occurs on every page, and similarly for the term footer. 
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9.1 Default Headers and Footers 


By default, each page has a centered page number as the header 
{9.2}. There is no default footer and no even/odd default headers or 
footers, except as specified in {9.9}. 


In a memorandum or a released paper, the page header on the first 
page is automatically suppressed provided a break does not occur 
before .MT is called. The macros and text of {6.9} and of {9} as 
well as .nr and .ds requests do not cause a break and are permitted 
before the .MT macro call. 


9.2 Page Header 


-PH [arg] 


For this and for the .EH, .OH, .PF, .EF, .OF macros, the argument 
is of the form: 


"*left-part’ center-part’ right-part’ " 


If it is inconvenient to use the apostrophe (’) as the delimiter (i.e., 
because it occurs within one of the parts), it may be replaced uni- 
formly by any other character. On output, the parts are left-justified, 
centered, and right-justified, respectively. See {9.11} for examples. 


The .PH macro specifies the header that is to appear at the top of 
every page. The initial value (as stated in {9.1}) is the default cen- 
tered page number enclosed by hyphens. The page number contained 
in the P register is an Arabic number. The format of the number 
may be changed by the .af request. 


If debug mode is set using the flag -rD1 on the command line {2.4}, 
additional information, printed at the top left of each page, is 
included in the default header. This consists of the SCCS!!°) Release 
and Level of MM (thus identifying the current version {12.3}), fol- 
lowed by the current line number within the current input file. 
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9.3 Even-Page Header 


.EH [arg] 
The .EH macro supplies a line to be printed at the top of each even- 


numbered page, immediately following the header. The initial value 
is a blank line. 


9.4 Odd-Page Header 


.OH [arg] 


This macro is the same as .EH, except that it applies to odd- 
numbered pages. 


9.5 Page Footer 


.PF [arg] 


The .PF macro specifies the line that is to appear at the bottom of 
each page. Its initial value is a blank line. If the -rCn flag is speci- 
fied on the command line {2.4}, the type of copy follows the footer 
on a separate line. In particular, if -rC3 or —-rC4 (DRAFT) is speci- 
fied, then, in addition, the footer is initialized to contain the date 
{6.7.1}, instead of being a blank line. 


9.6 Even-Page Footer 


-EF [arg] 


The .EF macro supplies a line to be printed at the bottom of each 
even-numbered page, immediately preceding the footer. The initial 
value is a blank line. 
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9.7 Odd-Page Footer 


.OF [arg] 


This macro is the same as .EF, except that it applies to odd- 
numbered pages. 


9.8 Footer on the First Page 


By default, the footer is a blank line. If, in the input text, one speci- 
fies .PF and/or .OF before the end of the first page of the document, 
then these lines will appear at the bottom of the first page. 


The header (whatever its contents) replaces the footer on the first 
page only if the -rN1 flag is specified on the command line {2.4}. 


9.9 Default Header and Footer with ‘“Section-Page”’ 
Numbering 


Pages can be numbered sequentially within sections {4.5}. To obtain 
this numbering style, specify -rN3 or -rNS on the command line. In 
this case, the default footer is a centered ‘‘section-page’’ number, 
e.g. 7-2, and the default page header is blank. 


9.10 Use of Strings and Registers in Header and 
Footer Macros 


String and register names may be placed in the arguments to the 
header and footer macros. If the value of the string or register is to 
be computed when the respective header or footer is printed, the invo- 
cation must be escaped by four (4) backslashes. This is because the 
string or register invocation will be processed three times: 


e as the argument to the header or footer macro; 
e in a formatting request within the header or footer macro; 


e ina .tl request during header or footer processing. 
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For example, the page number register P must be escaped with four 
backslashes in order to specify a header in which the page number is 
to be printed at the right margin, e.g.: 


.PH "’’’ Page \\\\nP’" 


creates a right-justified header containing the word ‘‘Page’’ followed 
by the page number. Similarly, to specify a footer with the ‘‘section- 
page’”’ style, one specifies (see {4.2.2.5} for meaning of H/): 


«PF "= \\\\n(HI1-\\\AnP —"" 


As another example, suppose that the user arranges for the string a/ 
to contain the current section heading which is to be printed at the 
bottom of each page. The .PF macro call would then be: 


»PF "?’\\\\4(a]’?" 


If only one or two backslashes were used, the footer would print a 
constant value for a], namely, its value when the .PF appeared in the 
input text. 


9.11 Header and Footer Example 


The following sequence specifies blank lines for the header and footer 
lines, page numbers on the outside edge of each page (i.e., top left 
margin of even pages and top right margin of odd pages), and ‘‘Revi- 
sion 3” on the top inside margin of each page: 


~.PH "on 
.PF nou 
»-EH "’\\\\nP’’ Revision 3°" 
.OH "’ Revision 3’’\\\\nP’" 


9.12 Generalized Top-of-Page Processing 


NOTE 


This section is intended only for users accustomed to writing 
formatter macros. 
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During header processing, MM invokes two user-definable macros. 
One, the .TP macro, is invoked in the environment (see .ev 
request!2]) of the header; the other, .PX, is a user-exit macro that is 
invoked (without arguments) when the normal environment has been 
restored, and with ‘‘no-space’” mode already in effect. 


The effective initial definition of .TP (after the first page of a docu- 
ment) is: 


.de TP 

sp 3 

th \\*(Ft 

wife th \\#(Fe 
wif o ’tl \\*(F0 
*sp 2 


The string }¢ contains the header, the string }e contains the even- 
page header, and the string }o contains the odd-page header, as 
defined by the .PH, .EH, and .OH macros, respectively. To obtain 
more specialized page titles, the user may redefine the .TP macro to 
cause any desired header processing {12.5}. Note that formatting 
done within the .TP macro is processed in an environment different 
from that of the body. 


For example, to obtain a page header that includes three centered 
lines of data, say, a document’s number, issue date, and revision 
date, one could define .TP as follows: 


.de TP 

Sp 

.ce 3 
777-888-999 

Iss, 2, AUG 1977 
Rev. 7, SEP 1977 


“Sp 


The .PX macro may be used to provide text that is to appear at the 
top of each page after the normal header and that may have tab stops 
to align it with columns of text in the body of the document. 
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9.13 Generalized Bottom-of-Page Processing 


.BS 
zero or more lines of text 
.BE 


Lines of text that are specified between the .BS (bottom-block start) 
and .BE (bottom-block end) macros will be printed at the bottom of 
each page,!® after the footnotes (if any), but before the page footer. 
This block of text is removed by specifying an empty block, i.e.: 


-BS 
BE 


9.14 Top and Bottom Margins 


.VM [top] [bottom] 


.VM (Vertical Margin) allows the user to specify extra space at the 
top and bottom of the page. This space precedes the page header and 
follows the page footer. .VM takes two unscaled arguments that are 
treated as v’s. For example: 


.VM 10 15 


adds 10 blank lines to the default top of page margin, and 15 blank 
lines to the default bottom of page margin. Both arguments must be 
positive (default spacing at the top of the page may be decreased by 
redefining .TP). 


18. The bottom block will appear on the table of contents pages and the cover 
sheet for Memorandum for File, but not on the Technical Memorandum or 
released-paper cover sheets. 
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9.15 Proprietary Markings 


.PM [code] 


.PM, for Proprietary Marking, appends to the page footer a 
PRIVATE, NOTICE, BELL LABORATORIES PROPRIETARY, or 
BELL LABORATORIES RESTRICTED disclaimer. The code may 
be: 


Meaning 
none turn off previous disclaimer, if any 
PRIVATE 
NOTICE 


BELL LABORATORIES PROPRIETARY 
BR BELL LABORATORIES RESTRICTED 


The disclaimers are in a form approved for use by the Bell System. 


9.16 Private Documents 


.nr Pv value 


The word “PRIVATE” may be printed centered and underlined on 
the second line of a document (preceding the page header). his is 
done by setting the Pv register: 


| Value Meaning 
0 do not print PRIVATE (default) 
1 PRIVATE on first page only 
2 PRIVATE on all pages 


If Pv is 2, the user definable .TP may not be used because .TP is 
used by MM to print PRIVATE on all pages except the first page of a 
memorandum on which .TP is not invoked. 
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10. Table of Contents and Cover Sheet 


The table of contents and the cover sheet for a document are pro- 
duced by invoking the .TC and .CS macros, respectively. 


NOTE 


This section will refer to cover sheets for Technical 
Memoranda and released papers only. The mechanism for 
producing a Memorandum for File cover sheet was discussed 
earlier {6.4}. 


These macros should normally appear only once at the end of the 
document, after the Signature Block {6.11.1} and Notations 
{6.11.2} macros. They may occur in either order. 


The table of contents is produced at the end of the document because 
the entire document must be processed before the table of contents 
can be generated. Similarly, the cover sheet is often not needed, and 
is therefore produced at the end. 


10.1 Table of Contents 


.TC [slevel] [spacing] [tlevel] [tab] [hd1] [hd2] [hd3] [hd4] [hd5] 


The .TC macro generates a table of contents containing the headings 
that were saved for the table of contents as determined by the value 
of the C/ register {4.4}. The arguments to .TC control the spacing 
before each entry, the placement of the associated page number, and 
additional text on the first page of the table of contents before the 
word “CONTENTS.” 


Spacing before each entry is controlled by the first two arguments; 
headings whose level is less than or equal to s/level will have spacing 
blank lines (halves of a vertical space) before them. Both slevel and 
spacing default to 1. This means that first-level headings are pre- 
ceded by one blank line (% a vertical space). Note that s/evel does not 
control what levels of heading have been saved; the saving of headings 
is the function of the C/ register {4.4}. 
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The third and fourth arguments control the placement of the page 
number for each heading. The page numbers can be justified at the 
right margin with either blanks or dots (“leaders”) separating the 
heading text from the page number, or the page numbers can follow 
the heading text. For headings whose level is less than or equal to 
tlevel (default 2), the page numbers are justified at the right margin. 
In this case, the value of rab determines the character used to 
separate the heading text from the page number. If rab is 0 (the 
default value), dots (i.e., leaders) are used; if tab is greater than 0, 
spaces are used. For headings whose level is greater than ¢level, the 
page numbers are separated from the heading text by two spaces (i.e., 
they are ‘‘ragged right’). 


All additional arguments (e.g., head! , head2, etc.), if any, are hor- 
izontally centered on the page, and precede the actual table of con- 
tents itself. 


If the .TC macro is invoked with at most four arguments, then the 
user-exit macro .T'X is invoked (without arguments) before the word 
“CONTENTS?” is printed; or the user-exit macro .TY is invoked and 
the word “CONTENTS” is nor printed. By defining .TX or .TY and 
invoking .TC with at most four arguments, the user can specify what 
needs to be done at the top of the (first) page of the table of contents. 
For example, the following input: 


.de TX 

ce 2 

Special Application 
Message Transmission 
ssp 2 

win +10n 

Approved: \I?31 

.in 

“Sp 

TC 


yields: 
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Special Application 
Message Transmission 


Approved: 


CONTENTS 


If this macro were defined as .TY rather than .TX, the word ““CON- 
TENTS” would not appear. Defining .TY as an empty macro will 
suppress ‘““CONTENTS” with no replacement: 


.de TY 


By default, the first level headings will appear in the table of contents 
at the left margin. Subsequent levels will be aligned with the text of 
headings at the preceding level. These indentations may be changed 
by defining the Ci string which takes a maximum of seven arguments 
corresponding to the heading levels. It must be given at least as 
many arguments as are set by the C/ register {4.4}. The arguments 
must be scaled. For example, with C/=5, 


ds Ci .25i .5i .75i Ui li 
or 


.ds Ci 0 2n 4n 6n &n 


Two other registers are available to modify the format of the table of 
contents, Oc and Cp. By default, table of contents pages will have 
lower-case Roman numeral page numbering. If the Oc register is set 
to 1, the .TC macro will not print any page number but will instead 
reset the P register to 1. It is the user’s responsibility to give an 
appropriate page footer to place the page number. Ordinarily the 
same .PF used in the body of the document will be adequate. 


The List of Figures, Tables, etc. pages will be produced separately 
unless Cp is set to 1 which causes these lists to appear on the same 
page as the table of contents. 
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10.2 Cover Sheet 


-CS [pages] [other] [total] [figs] [tbls] [refs] 


The .CS macro generates a cover sheet in either the released paper or 
Technical Memorandum style (see {6.4} for details of the Memoran- 
dum for File cover sheet). All the other information for the cover 
sheet is obtained from the data given before the .MT macro call 
{6.9}. If the Technical Memorandum style is used, the .CS macro 
generates the ‘‘Cover Sheet for Technical Memorandum.”’ The data 
that appear in the lower left corner of the Technical Memorandum 
cover sheet!) (the counts of: pages of text, other pages, total pages, 
figures, tables, and references) are generated automatically (0 is used 
for the count of ‘‘other pages’). These values may be changed by 
supplying the corresponding arguments to the .CS macro. If the 
released-paper style is used, all arguments to .CS are ignored. 


11. References 


There are two macros that delimit the text of references, a string used 
to automatically number the references, and an optional macro to 
produce reference pages within the document. 


11.1 Automatic Numbering of References 


Automatically numbered references may be obtained by typing \*(Rf 
(i.e., invoking the string Rf) immediately after the text to be refer- 
enced. This places the next sequential reference number (in a smaller 
point size) enclosed in brackets a half-line above the text to be refer- 
enced, as illustrated throughout this document. The reference count 
is kept in the number register Rf. 
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11.2 Delimiting Reference Text 


The .RS and .RF macros are used to delimit the text of each refer- 
ence. 


A line of text to be referenced\*(Rf. 
RS [string-name] 

reference text 

.RF 


11.3 Subsequent References 


-RS takes one argument, a string-name. For example: 


~RS aA 
reference text 
.RF 


The string aA is assigned the current reference number. It may be 
used later in the document, as the string call, \*(aA, to reference text 
which must be labeled with a prior reference number. The reference 
is output enclosed in brackets a half-line above the text to be refer- 
enced. No .RS/.RF pair is needed for subsequent references. 


11.4 Reference Page 


A reference page, entitled by default “References”, will be generated 
automatically at the end of the document (before the Table of Con- 
tents and the Cover Sheet) and will be listed in the Table of Contents. 
This page contains the reference items (i.e., text enclosed within 
.RS/.RF pairs). Reference items will be separated by a space (1/2 
space) unless the Ls register is set to 0 to suppress this spacing. The 
user may change the reference page title by defining the Rp string: 


.ds Rp "New Title" 
The .RP (Reference Page) macro may be used to produce reference 
pages anywhere else within a document (i.e., after each major sec- 


tion); .RP is not needed to produce a separate reference page with 
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default spacings at the end of the document. 
-RP [arg1] [arg2] 


The two arguments allow the user to control resetting of reference 
numbering and page skipping. 


argl Meaning 
0 reset reference counter (default) 
1 do not reset reference counter 


arg2 Meaning 
0 put on separate page (default) 
1 do not cause a following .SK 

2 do not cause a preceding .SK 
3 no .SK before or after 


If no .SK is issued by .RP, then a single blank line will separate the 
References from the following (preceding) text. The user may wish 
to adjust the spacing. For example, to produce references at the end 
of each major section: 


sp 3 
-RP12 
-H 1 "Next Section" 


12. Miscellaneous Features 
12.1. Bold, Italic, and Roman Fonts 


.B [bold-arg] [previous-font-arg] ... 
.I [italic-arg] [previous-font-arg] ... 


When called without arguments, .B changes the font to bold and .I 
changes to underlining (italic). This condition continues until the 
occurrence of a .R, when the (regular) roman font is restored. Thus: 
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a 

here is some text. 

.R 
yields: 

here is some text. 
If .B or .I is called with one argument, that argument is printed in 
the appropriate font (underlined in nroff for .I). Then the previous 
font is restored (underlining is turned off in nroff). If two or more 
arguments (maximum 6) are given to a .B or .I, the second argument 
is then concatenated to the first with no intervening space (1/12 space 


if the first font is italic), but is printed in the previous font; and the 
remaining pairs of arguments are similarly alternated. For example: 


-litalic " text " right -justified 
produces: 
italic text right-justified 
These macros alternate with the prevailing font at the time they are 


invoked. To alternate specific pairs of fonts, the following macros 
are available: 


IB  .BI .IR .RI .RB_ .BR 


Each takes a maximum of 6 arguments and alternates the arguments 
between the specified fonts. 


Note that font changes in headings are handled separately 
(4.2.2.4.1}. 


Anyone using a terminal that cannot underline might wish to insert: 


rm ul 
.rm cu 


at the beginning of the document to eliminate all underlining. 
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12.2 Justification of Right Margin 


SA [arg] 


The .SA macro is used to set right-margin justification for the main 
body of text. Two justification flags are used: current and default. - 
.SA 0 sets both flags to no justification, i.e., it acts like the .na 
request. .SA 1 is the inverse: it sets both flags to cause justification, 
just like the .ad request. However, calling .SA without an argument 
causes the current flag to be copied from the defaulr flag, thus per- 
forming either a .na or .ad, depending on what the default is. Ini- 
tially, both flags are set for no justification in nroff and for justifica- 
tion in troff. 


In general, the request .na can be used to ensure that justification is 
turned off, but .SA should be used to restore justification, rather than 
the .ad request. In this way, justification or lack thereof for the 
remainder of the text is specified by inserting .SA 0 or .SA 1 once at 
the beginning of the document. 


12.3 SCCS Release Identification 


The string RE contains the sccs!'°l Release and Level of the current 
version of MM. For example, typing: 


This is version \\*(RE of the macros. 


produces: 


This is version 15.130 of the macros. 


This information is useful in analyzing suspected bugs in MM. The 
easiest way to have this number appear in your output is to specify 
-rD1 {2.4} on the command line, which causes the string RE to be 
output as part of the page header {9.2}. 
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12.4 Two-Column Output 


MM can print two columns on a page: 


.2C 
text and formatting requests (except another .2C) 
AC 


The .2C macro begins two-column processing which continues until a 
.1C macro is encountered. In two-column processing, each physical 
page is thought of as containing two columnar ‘‘pages’’ of equal (but 
smaller) ‘‘page’’ width. Page headers and footers are nor affected by 
two-column processing. The .2C macro does not ‘‘balance’’ two- 
column output. 


It is possible to have full-page width footnotes and displays when in 
two column mode, although the default action is for footnotes and 
displays to be narrow in two column mode and wide in one column 
mode. Footnote and display width is controlled by a macro, .WC 
(Width Control), which takes the following arguments: 


arg Meaning 
N_ Normal default mode (—WF, —FF, —WD, FB) 
WF Wide Footnotes always (even in two column mode) 
—WF DEFAULT: turn off WF (footnotes follow column mode, 
wide in 1C mode, narrow in 2C mode, unless FF is set) 
FF First Footnote; all footnotes have the same width as the 
first footnote encountered for that page 
—FF DEFAULT: turn off FF (footnote style follows the settings 
of WF or —WF) 
WD Wide Displays always (even in two column mode) 
—WD DEFAULT: Displays follow whichever column mode is in 
effect when the display is encountered 
FB DEFAULT: Floating displays cause a break when output 
on the current page 


—FB_ Floating displays on current page do not cause a break 


For example: “.WC WD FF”’ will cause all displays to be wide, and 
all footnotes on a page to be the same width, while “.WC N” will 
reinstate the default actions. If conflicting settings are given to .WC 
the last one is used. That is, ““.\WC WF—WF” has the effect of 
“WC —WF”. 
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12.5 Column Headings for Two-Column Output 


NOTE 


This section is intended only for users accustomed to writing 
formatter macros. 


In two-column output, it is sometimes necessary to have headers over 
each column, as well as headers over the entire page {9}. This is 
accomplished by redefining the .TP macro {9.12} to provide header 
lines both for the entire page and for each of the columns. For 
example: 


.de TP 

sp 2 

.tl Page \\\\nP’? OVERALL”’ 
.tl > TITLE”? 

»sp 

nf 

.ta 16C 31R 34 SOC 65R 
left+center-right-left+center-right | (- stands for tab character) 
~first column---second column 
fi 

“sp 2 


The above example will produce two lines of page header text plus 
two lines of headers over each column. The tab stops are for a 65-en 
overall line length. 


12.6 Vertical Spacing 


.SP [lines] 


There exist several ways of obtaining vertical spacing, all with dif- 
ferent effects: the .sp request spaces the number of lines specified, 
unless “no space’? (.ns) mode is on, in which case the request is 
ignored. This mode is set at the end of a page header to eliminate 
spacing by a .sp or .bp request that happens to occur at the top of a 
page. This mode can be turned off by the .rs (‘‘restore spacing’’) 
request. 
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The .SP macro is used to avoid the accumulation of vertical space by 
successive macro calls. Several .SP calls in a row produce not the sum 
of their arguments, but their maximum; 1.e., the following produces 
only 3 blank lines: 


.SP 2 
SP 3 
SP 


Many MM macros utilize .SP for spacing. For example, “.LE 1” 
{5.3.2} immediately followed by ‘‘.P”’ £4.1} produces only a single 
blank line (% a vertical space) between the end of the list and the fol- 
lowing paragraph. An omitted argument defaults to one blank line 
(one vertical space). Negative arguments are not permitted. The 
argument must be unscaled but fractional amounts are permitted. 
Like .sp, .SP is also inhibited by the .ns request. 


12.7 Skipping Pages 


.SK [pages] 


The .SK macro skips pages, but retains the usual header and footer 
processing. If pages is omitted, null, or 0, .SK skips to the top of the 
next page unless it is currently at the top of a page, in which case it 
does nothing. .SK n skips n pages. That is, .SK always positions the 
text that follows it at the top of a page, while .SK 1 always leaves 
one page that is blank except for the header and footer. 


12.8 Forcing an Odd Page 


OP 


This macro is used to ensure that the text following it begins at the 
top of an odd-numbered page. If currently at the top of an odd page, 
no motion takes place. If currently on an even page, text resumes 
printing at the top of the next page. If currently on an odd page (but 
not at the top of the page) one blank page is produced, and printing 
resumes on the page after that. 
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12.9 Setting the Point Size and Vertical Spacing 


In troff, the default point size (obtained from the MM register S 
{2.4}) is 10 points, and the vertical spacing is 12 points (i.e., 6 lines 
per inch). The prevailing point size and vertical spacing may be 
changed by invoking the .S macro: 


.S [point size] [vertical spacing] 


The mnemonics D (default value), C (current value), and P (previous 
value) may be used for both arguments. If an argument is negative, 
the current value is decremented by the specified amount; if an argu- 
ment is positive, the current value is incremented by the specified 
amount; if an argument is unsigned, it is used as the new value; .S 
without arguments defaults to P. If the first argument is specified but 
the second is not, then D is used for the vertical spacing; the default 
value for vertical spacing is always 2 points greater than the current 
point size.!? A null ("") value for either argument defaults to C. 
Thus, if m is a numeric value: 


S = .SPP 
Ss" = .SCn 
Sn = .Snc 
Sn = .SnD 
sun = 14S €-D 
Sunouns = SCC 
Sunn = .Snn 


If the first argument is greater than 99, the default point size (10 
points) is restored. If the second argument is greater than 99, the 
default vertical spacing (current point size plus 2 points) is used. For 
example: 


5 100 
14111 


.5 10 12 
.S 14 16 


The .SM macro allows one to reduce by 1 point the size of a string: 


19, Footnotes {8} are two points smaller than the body, with an additional three- 
point space between footnotes. 
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.SM string] [string2] [string3] 


If the third argument is omitted, the first argument is made smaller 
and is concatenated with the second argument, if the latter is speci- 
fied. If all three arguments are present (even if any are null), the 
second argument is made smaller and all three arguments are con- 
catenated. For example: 


SM X gives xX 

SM X Y gives XY 
SM Y X Y gives YXY 
«SM UNIX gives UNIX 
.SM UNIX ) gives UNIX) 
.SM ( UNIX ) | gives (UNIX) 
.SM U NIX "" gives UNIX 


12.10 Producing Accents 


The following strings may be used to produce accents for letters: 


Input Output 


Grave accent e\*~ € 
Acute accent e\e- € 
Circumflex o\** 6 
Tilde n\*~ ih 
Cedilla c\e,  ¢ 
Lower-case umlaut u\*: 
Upper-case umlaut U\*, U 


12.11 Inserting Text Interactively 


-RD [prompt] [diversion] [string] 


-RD (ReaD insertion) allows a user to stop the standard output of a 
document and to read text from the standard input until two consecu- 
tive new-lines are found. When the new-lines are encountered, nor- 
mal output is resumed. 
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-RD follows the formatting conventions in effect. Thus, the examples 
below assume that the .RD is invoked in no fill mode (.nf). 


The first argument is a prompt which will be printed at the terminal. 
If no prompt is given, .RD signals the user with a BEL on terminal 
output. 


The second argument, the name of a diversion, allows the user to save 
all the text typed in after the prompt in a macro whose name is that 
of the diversion. The third argument, the name of a string, allows 
the user to save for later reference the first line following the prompt 
in the named string. For example: 


.RD Name aA bB 
produces: 
Name: (user types) J. Jones 


16 Elm Rd., 
Piscataway 


The diverted macro .aA will contain: 


J. Jones 
16 Elm Rd., 
Piscataway 
The string bB (\*(bB) contains ‘J. Jones’. 


A new-line followed by a control-d (EOF) also allows the user to 
resume normal output. 


13. Errors and Debugging 
13.1 Error Terminations 


When a macro discovers an error, the following actions occur: 
e A break occurs. 


e To avoid confusion regarding the location of the error, the for- 
matter output buffer (which may contain some text) is printed. 


e A short message is printed giving the name of the macro that 
found the error, the type of error, and the approximate line 
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number (in the current input file) of the last processed input 
line. (All the error messages are explained in Appendix D.) 


e Processing terminates, unless the register D {2.4} has a posi- 
tive value. In the latter case, processing continues even 
though the output is guaranteed to be deranged from that 
point on. 


NOTE 


The error message is printed by writing it directly to the user’s 
terminal. If an output filter, such as 300(1), 450(/), or hp(1) 
is being used to post-process nroff output, the message may be 
garbled by being intermixed with text held in that filter’s out- 
put buffer. 


If any of cw(1), eqn(/)/neqn, and tbi(/) are being used, and if 
the -olist option of the formatter causes the last page of the 
document not to be printed, a harmless “broken pipe’? message 
may result. 


13.2 Disappearance of Output 


This usually occurs because of an unclosed diversion (e.g., missing 
.DE or .FE). Fortunately, the macros that use diversions are careful 
about it, and they check to make sure that illegal nestings do not 
occur. If any message is issued about a missing .DE or .FE, the 
appropriate action is to search backwards from the termination point 
looking for the corresponding .DF, .DS, or .FS. 


The following command: 
grep —n "*\.[EDFRT][EFNQS]" files... 


prints all the .DF, .DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS, 
and .TE macros found in files ..., each preceded by its file name and 
the line number in that file. This listing can be used to check for ille- 
gal nesting and/or omission of these macros. 
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14. Extending and Modifying the Macros 


14.1 Naming Conventions 


In this section, the following conventions are used to describe names: 


digit 


235% > 2 2 


lower-case letter 

upper-case letter 

n, a, or A:i.e., any letter or digit (any alphanumeric character) 
special character (any non-alphanumeric character) 


All other characters are literals (i.e., stand for themselves). 


Note that request, macro, and string names are kept by the formatters 
in a single internal table, so that there must be no duplication among 
such names. Number register names are kept in a separate table. 


14.1.1 Names Used by Formatters 


requests: 


registers: 


aa (most common) 
an (only one, currently: ¢2) 


aa (normal) 

-X (normal) 

-s (only one, currently: .$) 
a. (only one, currently: c.) 
% (page number) 


14.1.2 Names Used by MM 


macros 
and 
strings: 


A, AA, Aa (accessible to users; e.g., macros P and 
HU, strings F, BU, and Lt) 

nA (accessible to users; only two, currently: 1C and 2C) 
aA (accessible to users; only one, currently: nP) 

s (accessible to users; only the seven accents, currently 
€12.10}) 

)x, x, ]x, >x, ?x (internal) 
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registers: An, Aa (accessible to users; e.g., H1, Fg) 
A (accessible to users; meant to be set on the command 
line; e.g., C) 
2X, 3X, #x, ?x, !x (internal) 


14.1.3 Names Used by CW, EQN/NEQN, and TBL 


Cw(1), the constant-width font preprocessor for troff, uses the follow- 
ing five macro names: .CD, .CN, .CP, .CW, and .PC; it also uses 
the number register names cE and cW. The equation preprocessors, 
eqn(1) and negn use registers and string names of the form nn. The 
table preprocessor, rb/(1), uses T&, T#, and TW, and names of the 
form: 


a- at al nn na “a #a — #s 


14.1.4 User-Definable Names. 


Given the above, what is left for user extensions? To avoid ‘‘colli- 
sions” with already used names, use names that consist either of a 
single lower-case letter, or of a lower-case letter followed by a charac- 
ter other than a lower-case letter (remembering, however, that the 
names .c2 and .nP are already used). The following is a possible user 
naming convention: 


macros: aA (e.g., bG, kW) 
strings: as (e.g., c), f], pd) 


registers: a (e.g., f, t) 
14.2 Sample Extensions 
14.2.1 Appendix Headings 


The following is a way of generating and numbering appendix head- 
ings: 
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wnr Hu 1 

-nraQ 

.de aH 

nra+l 

nr PO 

.PH "*’’ Appendix \\na-\\\\nP*" 
SK 

HU "\\$1 " 


After the above initialization and definition, each call of the form 
“aH "title""’ begins a new page (with the page header changed to 
‘Appendix a-n’’) and generates an unnumbered heading of title, 
which, if desired, can be saved for the table of contents. Those who 
wish apppendix titles to be centered must, in addition, set the register 
He to 1 £4.2.2.3}. 


14.2.2 Hanging Indent with Tabs 


The following example illustrates the use of the hanging-indent 
feature of variable-item lists {5.3.3.6}. First, a user-defined macro 
is built to accept four arguments that make up the mark. In the out- 
put, each argument is to be separated from the previous one by a tab, 
tab settings are defined later. Since the first argument may begin 
with a period or apostrophe, the ““\&”’ is used so that the formatter 
will not interpret such a line as a formatter request or macro call.2° 
The ‘\t” is translated by the formatter into a tab. The “\c” is used 
to concatenate the input text that follows the macro call to the line 
built by the macro. The macro and an example of its use are: 


20. The two-character sequence ‘‘\&’’ is understood by the formatters to be a 
“‘zero-width”’ space, i.e., it causes no output characters to appear, but it 
removes the special meaning of a leading period or apostrophe. 
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.de aX 
.LI 
V&ANSIA\IN\ASZA\TANS3\IAAS4A tc 


.ta 7n 15n 25n 30n 

.VL 30 

.aX .nh off \- no 

No hyphenation. 

Automatic hyphenation is turned off. 

Words containing hyphens 

(e.g., mother-in-law) may still be split across lines. 

.axX .hy on \- no 

Hyphenate. 

Automatic hyphenation is turned on. 

.aX .hc\Ce none none no (G stands for a space) 
Hyphenation indicator character is set to “‘c’’ or removed. 
During text processing the indicator is suppressed 

and will not appear in the output. 

Prepending the indicator to a word has the effect 

of preventing hyphenation of that word. 

.LE 


The resulting output is: 


.nh off —_ no No hyphenation. Automatic 
hyphenation is turned off. Words 
containing hyphens (e.g., mother- 
in-law) may still be split across 
lines. 


hy on — no Hyphenate. Automatic hyphena- 
tion is turned on. 


-hec none none no Hyphenation indicator character is 
set to “‘c’’ or removed. During 
text processing the indicator is 
suppressed and will not appear in 
the output. Prepending the indi- 
cator to a word has the effect of 
preventing hyphenation of that 
word. 
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15. Conclusion 


The following are the qualities that we have tried to emphasize in 
MM, in approximate order of importance: 


e Robustness in the face of error—A user need not be an 
nroff/troff expert to use these macros. When the input is 
incorrect, either the macros attempt to make a reasonable 
interpretation of the error, or a message describing the error is 
produced. We have tried to minimize the possibility that a 
user would get cryptic system messages or strange output as a 
result of simple errors. 


e Ease of use for simple documents—It is not necessary to write 
complex sequences of commands to produce simple documents. 
Reasonable default values are provided, where at all possible. 


e Parameterization—There are many different preferences in the 
area of document styling. Many parameters are provided so 
that users can adapt the output to their respective needs over a 
wide range of styles. 


e Extension by moderately expert users—We have made a strong 
effort to use mnemonic naming conventions and consistent 
techniques in the construction of the macros. Naming conven- 
tions are given so that a user can add new macros or redefine 
existing ones, if necessary. 


@ Device independence-—The most common use of MM is to print 
documents on hard-copy typewriter terminals, using the nroff 
formatter. The macros can be used conveniently with both 10- 
and 12-pitch terminals. In addition, output can be scanned 
with an appropriate CRT terminal. The macros have been 
constructed to allow compatibility with sroff, so that output can 
be produced both on typewriter-like terminals and on a photo- 
typesetter. 


@ Minimization of input—The design of the macros attempts to 
minimize repetitive typing. For example, if a user wants to 
have a blank line after all first- or second-level headings, he or 
she need only set a specific parameter once at the beginning of 
a document, rather than add a blank line after each such head- 
ing. 


e Decoupling of input format from output style—There is but one 
way to prepare the input text, although the user may obtain a 
number of output styles by setting a few global flags. For 
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example, the .H macro is used for all numbered headings, yet 
the actual output style of these headings may be made to vary 
from document to document or, for that matter, within a sin- 
gle document. 
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Appendix A: User-defined List Structures 


NOTE 


This appendix is intended only for users accustomed to writing 


formatter macros. 


If a large document requires complex list structures, it is useful to be 
able to define the appearance for each list level only once, instead of 
having to define it at the beginning of each list. This permits con- 
sistency of style in a large document. For example, a generalized 
list-initialization macro might be defined in such a way that what it 
does depends on the list-nesting level in effect at the time the macro 
is called. Suppose that levels 1 through 5 of lists are to have the fol- 
lowing appearance: 


The following code defines a macro (.aL) that always begins a new 
list and determines the type of list according to the current list level. 
To understand it, you should know that the number register :g is 
used by the MM list macros to determine the current list level; it is 0 
if there is no currently active list. Each call to a list-initialization 
macro increments -g, and each .LE call decrements it. 
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.de aL 


NH register g is used as a local temporary to save :g 
before it is changed below 
nr g \\n(ig 


Jif \\ng=0.AL A \" give me an A. 

if \\ng=1 .LB \\n(Li 0 1 4 \" give me a [1] 
.if \\ng=2 .BL \" give me a bullet 

af \\ng=3 .LB \\n(Li 0 2 2 a \" give me an a) 
.if \\ng=4 .ML + \" give me a + 


This macro can be used (in conjunction with .LI and .LE) instead of 
.AL, .RL, .BL, .LB, and .ML. For example, the following input: 


eal 

-LI 

first line. 
.aL 

-LI 

second line. 
.LE 

LI 

third line. 
.LE 


will yield: 
A. first line. 
[1] second line. 
B. _ third line. 


There is another approach to lists that is similar to the .H mechan- 
ism. The list-initialization, as well as the .LI and the .LE macros are 
all included in a single macro. That macro (called .bL below) 
requires an argument to tell it what level of item is required; it 
adjusts the list level by either beginning a new list or setting the list 
level back to a previous value, and then issues a .LI macro call to 
produce the item: 
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-de bL 

ie \\n(.$ .nr g \\$1 \" if there is an argument, that is the level 
-el .nr g \\n(:g \" if no argument, use current level 

wif \Ang-\\n(:g>1 .)D "**ILLEGAL SKIPPING OF LEVEL" 

\" increasing level by more than 1 

af \\ng>\\n(g \{.aL \\ng-1 \" if g > 2g, begin new list 

. nrg \\n(:g\} \" and reset g to current level (.aL changes g) 

if \\n(:g>\\ng .LC \\ng \" if :g > g, prune back to correct level 
*\" if sg = g, stay within current list 

.LI \" in all cases, get out an item 


For .bL to work, the previous definition of the .aL macro must be 
changed to obtain the value of g from its argument, rather than from 
.g. Invoking .bL without arguments causes it to stay at the current 
list level. The MM .LC macro (List Clear) removes list descriptions 
until the level is less than or equal to that of its argument. For exam- 
ple, the .H macro includes the call ‘“.LC 0”. If text is to be resumed 
at the end of a list, insert the call ‘‘.LC 0” to clear out the lists com- 
pletely. The example below illustrates the relatively small amount of 
input needed by this approach. The input text: 


The quick brown fox jumped over the lazy dog’s back. 
-bL 1 

first line. 
-bL 2 
second line. 
.bL 1 

third line. 
-bL 

fourth line. 
.LC 0 

fifth line. 


yields: 
The quick brown fox jumped over the lazy dog’s back. 
A. first line. 
[1] second line. 
B. third line. 


C. fourth line. 
fifth line. 


9—94 Programmer's Guide: CTIX Supplement 


Appendix B: Sample Footnotes 


The following example illustrates several footnote styles and both 
labeled and automatically-numbered footnotes. The actual input for 
the immediately following text and for the footnotes at the bottom of 
this page is shown on the following page: 


With the footnote style set to the nroff default, we process a footnote! 
followed by another one.***** Using the .FD macro, we changed 
the footnote style to hyphenate, right margin justification, indent, and 
left justify the label. Here is a footnote,” and another.t The foot- 
note style is now set, again via the .FD macro, to no hyphenation, no 
right margin justification, no indentation, and with the label left- 
justified. Here comes the final one.* 


1. This is the first footnote text example (.FD 10). This is the default style for 
nroff. The right margin is not justified. Hyphenation is not permitted. The 
text is indented, and the automatically generated label is right-justified in the 
text-indent space. 

*eee® This is the second footnote text example (.FD 10). This is also the default 
nroff style but with a long footnote label provided by the user. 

2. This is the third footnote example (.FD 1). The right margin is justified, the 
footnote text is indented, the label is /eft-justified in the text-indent space. 
Although not necessarily illustrated by this example, hyphenation is permitted. 
The quick brown fox jumped over the lazy dog’s back. 

{ This is the fourth footnote example (.FD 1). The style is the same as the third 
footnote. 

3. This is the fifth footnote example (.FD 6). The right margin is not justified, 

hyphenation is not permitted, the footnote text is not indented, and the label is 

placed at the beginning of the first line. The quick brown fox jumped over the 

lazy dog’s back. Now is the time for all good men to come to the aid of their 

country. 
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.FD 10 

With the footnote style set to the 

«I nroff 

default, we process a footnote\*F 

.FS 

This is the first footnote text example (.FD 10). This is the default style for 
.[ nroff. 

The right margin is 

I] not 

justified. Hyphenation is 

I not 

permitted. The text is indented, and the automatically generated label is 
«I right -justified 

in the text-indent space. 

.FE 

followed by another onc. ee \O (© stands for a space) 
WES 

This is the second footnote text example (.FD 10). 

This is also the default 

.[ nroff 

style but with a long footnote label provided by the user. 

.FE 

FDI 

Using the .FD macro, we changed the footnote style to 

hyphenate, right margin justification, indent, and left justify the label. 
Here is a footnote, \*F 

«FS 

This is the third footnote example (.FD 1). 

The right margin is justified, the footnote text is indented, the label is 
ot left -justified 

in the text-indent space. 

Although not necessarily illustrated by this example, hyphenation is permitted. 
The quick brown fox jumped over the lazy dog's back. 

.FE 

and another. \(dg\O 

«FS \(dg 

This is the fourth footnote example (.FD 1). 

The style is the same as the third footnote. 

FE 

.FD6 

The footnote style is now set, again via the .FD macro, to no hyphenation, no right margin 
justification, no indentation, and with the label left-justified. 

Here comes the final one.\*F\O 

FS 

This is the fifth footnote example (.FD 6). The right margin is 

not 

justified, hyphenation is 

-[ not 

permitted, the footnote text is 

.P not 

indented, and the label is placed at the beginning of the first line. 

The quick brown fox jumped over the lazy dog’s back. 

Now is the time for all good men to come to the aid of their country. 
.PE 
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Appendix C: Sample Letter 


Input: 


«ND "May 31, 1979" 

-TL 334455 

Out-of-Hours Course Description 

.AU "D. W. Stevenson" DWS PY 9876 5432 1X-123 

-MT 0 

-DS 

J. M. Jones: 

.DE 

.P 

Please use the following description for the Out-of-Hours course 
J 

Document Preparation on the UNIX* 

R 

-FS * 

UNIX is a trademark of Bell Laboratories. 

.FE 

-I "Time-Sharing System:" 

-P 

The course is intended for clerks, typists, and others who intend to use the 
UNIX system for preparing documentation. 

The course will cover such topics as: 

-VL 18 

«LI Environment: 

utilizing a time-sharing computer system; 

accessing the system; using appropriate output terminals. 
-LI Files: 

how text is stored on the system; directories; manipulating files. 
-LI "Text editing:" 

how to enter text so that subsequent revisions are easier to make; 
how to use the editing system to add, delete, and move lines 
of text; how to make corrections. 

-LI "Text processing: " 

basic concepts; use of general-purpose formatting packages. 
-LI "Other facilities: " 

additional capabilities useful to the typist such as the 

-I "spell, diff, 

and 

.I grep 

commands, and a desk-calculator package. 

«LE 

.SG jrm 

«NS 

S. P. Lename 

H. O. Del 

M. Hill 

NE 
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Bell Laboratories 


subject: Out-of-Hours Course date: May 31, 1979 
Description 
Case: 334455 from: D. W. Stevenson 
PY 9876 


1X-123 x5432 


J. M. Jones: 


Please use the following description for the Out-of- 
Hours course ~~Document Preparation on the UNIX* Time- 
Sharing System": 


The course is intended for clerks, typists, and others 
who intend to use the UNIX system for preparing docu- 
mentation. The course will cover such topics as: 


Environment: utilizing a time-sharing computer 
system; accessing the system; using 
appropriate output terminals. 


Files: how text is stored on the system; 
directories; manipulating files. 


Text editing: how to enter text so that subsequent 
revisions are easier to make; how to 
use the editing system to add, 
delete, and move lines of text; how 
to make corrections. 


Text processing: basic concepts; use of general- 
purpose formatting packages. 


Other facilities: additional capabilities useful to 


the typist such as the gpel]l, diff, 
and grep commands, and a desk-~ 


calculator package. 
PY-9876-DWS-jrm D. W. Stevenson 
Copy to 
S. P. Lename 


H. QO. Del 
M. Hill 


* UNIX is a trademark of Bell Laboratories. 
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Bell Laboratories 


subject! Out-of-Hours Course Description - date: May 31, 1979 


Case 334455 


J. M. Jones: 


from: D. W. Stevenson 
PY 9876 
1X-123 x5432 


Please use the following description for the Out-of-Hours course Document 
Preparation on the UNIX* Time-Sharing System: 


The course is intended for clerks, typists, and others who intend to use the 
UNIX system for preparing documentation. The course will cover such 


topics as: 


Environment: 


Files: 


Text editing: 


Text processing: 


Other facilities: 


PY-9876-DWS-jrm 


Copy to 

S. P. Lename 
H. O. Del 
M. Hill 


utilizing a time-sharing computer system; accessing the 
system; using appropriate output terminals. 


how text is stored on the system; directorics; 
manipulating files. 


how to enter text so that subsequent revisions are easier 
to make; how to use the editing system to add, delcte, 
and move lines of text; how to make corrections. 


basic concepts; use of general-purpose formatting 
packages. 


additional capabilities useful to the typist such as the 
spell, diff, and grep commands, and a desk-calculator 
package. 


D. W. Stevenson 


* UNIX is a trademark of Bell Laboratories. 
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Appendix D: Error Messages 
I. MM Error Messages 


An MM error message has a standard part followed by a variable part. 
The standard part has the form: 


ERROR: (filename )input line n: 


The variable part consists of a descriptive message, usually beginning 
with a macro name. The variable parts are listed below in alphabeti- 
cal order by macro name, each with a more complete explanation:7! 


Check TL, AU, AS, AE, MT sequence The correct order of mac- 
ros at the start of a 
memorandum is shown in 
{6.9}. Something has 
disturbed this order. If 
-AS 2 was used, then the 
error message will be 
“Check TL, AU, AS, 
AE, NS, NE, MT 
sequence’. 


CS:cover sheet too long The text of the cover sheet 
is too long to fit on one 
page. The abstract should 
be reduced or the indent 
of the abstract should be 
decreased {6.4}. 


DE:no DS or DF active .DE has been encountered 
but there has not been a 
previous .DS or .DF to 
match it. 


DF:illegal inside TL or AS Displays are not allowed 
in the title or abstract. 


21. This list is set up by ‘‘.LB 37 0 2 0” {5.4}. 


9—]00 Programmer's Guide: CTIX Supplement 


DF:missing DE 


DF:missing FE 


DF:too many displays 


DS:illegal inside TL or AS 


DS:missing DE 


DS:missing FE 


FE:no FS active 


FS:missing DE 


FS:missing FE 


H:bad arg:value 
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-DF occurs within a 
display, i.e., a .DE has 
been omitted or mistyped. 


A display starts inside a 
footnote. The likely cause 
is the omission (or 
misspelling) of a .FE to 
end a previous footnote. 


More than 26 floating 
displays are active at once, 
i.e., have been accumu- 
lated but not yet output. 


Displays are not allowed 
in the title or abstract. 


-DS occurs” within a 
display, i.e., a .DE has 
been omitted or mistyped. 


A display starts inside a 
footnote. The likely cause 
is the omission (or 
misspelling) of a .FE to 
end a previous footnote. 


.FE has been encountered 
with no previous .FS to 
match it. 


A footnote starts inside a 
display, i.e., a .DS or .DF 
occurs without a matching 
.DE. 


A previous .FS was not 
matched by a closing .FE, 
i.e€., an attempt is being 
made to begin a footnote 
inside another one. 


The first argument to .H 
must be a single digit from 
1 to 7, but va/ue has been 
supplied instead. 


9—10] 


H:missing arg 


H:missing DE 


H:missing FE 


HU: missing arg 
LB:missing arg(s) 


LB:too many nested lists 


LE:mismatched 


Lino lists active 


ML missing arg 


ND-:missing arg 
RF:no RS active 


RP:missing RF 


-H needs at least 1 argu- 
ment. 


A heading macro (.H or 
-HU) occurs inside a 
display. 


A heading macro (.H or 
-HU) occurs inside a foot- 
note. 


-HU needs 1 argument. 


-LB requires at least 4 
arguments. 


Another list was started 
when there were already 6 
active lists. 


-LE has occurred without 
a previous .LB or other 
list-initialization macro 
{5.3.3}. Although this is 
not a fatal error, the mes- 
sage is issued because 
there almost certainly 
exists some problem in the 
preceding text. 


-LI occurs without a 
preceding list-initialization 
macro. The latter has 
probably been omitted, or 
has been separated from 
the .LI by an intervening 
-H or .HU. 


-ML requires at least 1 
argument. 


-ND requires 1 argument. 


«RF has been encountered 
with no previous .RS to 
match it. 


A previous .RS was not 
matched by a closing .RF. 
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RS:missing RF A _ previous .RS was not 
matched by a closing .RF. 


S:bad arg:value The incorrect argument 
value has been given for 
.S, see 12.9}. 


SA:bad arg:value The argument to .SA (if 
any) must be either 0 or 1. 
The incorrect argument is 
shown as value. 


SG:missing DE .SG_ occurs inside a 
display. 


SG:missing FE .SG occurs inside a foot- 
note. 


SG:no authors .SG occurs without any 
previous .AU macro(s). 


VL:missing arg .VL requires at least 1 
argument. 


WC:unknown option An incorrect argument has 
been given to .WC, see 
{12.4}. 


ll. Formatter Error Messages 


Most messages issued by the formatter are self-explanatory. Those 
error messages over which the user has (some) control are listed 
below. Any other error messages should be reported to the local 
system-support group. 


“Cannot do ev” is caused by (a) setting a page width that is negative 
or extremely short; (b) setting a page length that is negative or 
extremely short; (c) reprocessing a macro package (e.g., per- 
forming a .so formatter request on a macro package that was 
already requested on the command line); and (d) requesting the 
troff —s1 option on a document that is longer than ten pages. 


’ 


“Cannot execute filename’ 
the filename. 


is given by the .! request if it cannot find 


“Cannot open filename” is issued if one of the files in the list of files 
to be processed cannot be opened. 
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“Exception word list full’? indicates that too many words have been 
specified in the hyphenation exception list (via .hw requests). 


“Line overflow’ means that the output line being generated was too 
long for the formatter’s line buffer. The excess was discarded. 
See the ‘‘Word overflow’? message below. 


“Non-existent font type’? means that a request has been made to 
mount an unknown font. 


‘“‘Non-existent macro file’ means that the requested macro package 
does not exist. 


‘Non-existent terminal type” means that the terminal options refers 
to an unknown terminal type. 


“Out of temp file space’? means that additional temporary space for 
macro definitions, diversions, etc. cannot be allocated. This 
message often occurs because of unclosed diversions (missing 
.FE or .DE), unclosed macro definitions (e.g., missing ‘‘..’’), 
or a huge table of contents. 


“Too many page numbers” is issued when the list of pages specified 
to the formatter —o option is too long. 


“Too many number registers’”” means that the pool of number register 
names is full. Unneeded registers can be deleted by using the 
.Tr request. 


“Too many string/macro names” is issued when the pool of string and 
macro names is full. Unneeded strings and macros can be 
deleted using the .rm request. 


‘“Word overflow’? means that a word being generated exceeded the 
formatter’s word buffer. The excess characters were discarded. 
A likely cause for this and for the ‘“‘Line overflow” message 
above are very long lines or words generated through the misuse 
of \c or of the .cu request, or very long equations produced by 
eqn (1)/negn. 
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Appendix E: Summary of Macros, Strings, and 
Number Registers 


I. Macros 


The following is an alphabetical list of macro names used by MM. 
The first line of each item gives the name of the macro, a brief 
description, and a reference to the section in which the macro is 
described. The second line gives a prototype call of the macro. 


Macros marked with an asterisk are nor, in general, invoked directly 
by the user. Rather, they are ‘“‘user exits’ defined by the user and 
called by the MM macros from inside header, footer, or other macros. 


1C One-column processing {12.4} 
.1C 

2C Two-column processing {12.4} 
2C 

AE Abstract end {6.4} 
AE 


AF Alternate format of ‘‘Subject/Date/From”’ block {6.7.2} 
.AF [company-name] 


AL Automatically-incremented list start {5.3.3.1} 
.AL [type] [text-indent] [1] 


AS Abstract start {6.4} 
-AS [arg] [indent] 


AT Author’s title {6.2} 
.AT [title] ... 


AU Author information {6.2} 
-AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] [arg] 


AV Approval signature 6.11.3} 


-AV [name] 
B Bold {12.1} 

.B [bold-arg] [previous-font-arg] [bold] [prev] [bold] [prev] 
BE Bottom Block End {9.13} 

.BE 
BI Bold/Italic {12.1} 


-BI [bold-arg] [italic-arg] [bold] [italic] [bold] [italic] 
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BL Bullet list start {5.3.3.2} 
-BL {text-indent] [1] 


BR Bold/Roman {12.1} 
-BR_ [bold-arg] [Roman-arg] [bold] [Roman] [bold] 
[Roman] 


BS Bottom Block Start {9.13} 
.BS 


CS Cover sheet {10.2} 
.CS [pages] [other] [total] [figs] [tbls] [refs] 


DE Display end {7.1} 
.DE 


DF Display floating start {7.2} 
.DF [format] [fill] [right-indent] 


DL Dash list start {5.3.3.3} 
.DL [text-indent] [1] 


DS Display static start {7.1} 
-DS [format] [fill] [right-indent] 


EC Equation caption {7.5} 
-EC [title] [override] [flag] 


EF Even-page footer {9.6} 
.EF [arg] 

EH Even-page header {9.3} 
-EH [arg] 

EN End equation display {7.4} 
.EN 

EQ Equation display start {7.4} 
-EQ [label] 


EX Exhibit caption {7.5} 
-EX [title] [override] [flag] 


FC Formal closing {6.11} 
-FC [closing] 


FD Footnote default format {8.3} 
-FD [arg] [1] 


FE Footnote end {8.2} 
.FE 
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FG 


LB 


LC 


LE 


LI 


Figure title {7.5} 
.FG [title] [override] [flag] 


Footnote start (8.2} 
-FS [label] 


Heading—numbered {4.2} 
-H level [heading-text] [heading-suffix] 


Hyphenation character {3.4} 
-HC [hyphenation-indicator] 


Heading mark style (Arabic or Roman numerals, or letters) 
£4.2.2.5} 

-HM {argl} ... [arg7] 

Heading—unnumbered {4.3} 

-HU heading-text 


Heading user exit X (before printing heading) 4.6} 
~HX dlevel rlevel heading-text 


Heading user exit Y (before printing heading) {4.6} 
-HY dlevel rlevel heading-text 


Heading user exit Z (after printing heading) {4.6} 

-HZ dlevel rlevel heading-text 

Italic (underline in nroff) {12.1} 

.I [italic-arg] [previous-font-arg] [italic] [prev] [italic] [prev] 
Italic/Bold {12.1} 

.IB [italic-arg] [bold-arg] [italic] [bold] [italic] [bold] 
Italic/Roman {12.1} 

.IR_ [italic-arg] [Roman-arg] [italic] [Roman] _ [italic] 
[Roman] 

List begin {5.4} 

-LB text-indent mark-indent pad type [mark] [LI-space] 
[LB-space] 


List-status clear { Appendix A} 
.LC [list-level] 


List end (5.3.2} 
-LE [1] 


List item (5.3.1} 
.LI [mark] [1] 
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ML Marked list start {5.3.3.4} 
.-ML mark [text-indent] [1] 


MT Memorandum type {6.6} 
-MT [type] [addressee] or .MT [4] [1] 


ND New date {6.7.1} 


.ND new-date 
NE Notation end {6.11.2} 
.NE 
NS Notation start {6.11.2} 
-NS [arg] 
nP Double-line indented paragraphs {4.1} 
.nP 
OF Odd-page footer {9.7} 
.OF [arg] 
OH Odd-page header {9.4} 
.OH [arg] 
OK Other keywords for the Technical Memorandum cover sheet 
{6.5} 


-OK [keyword] ... 


OP Odd page {12.8} 
.OP 

P Paragraph {4.1} 
-P [type] 

PF Page footer {9.5} 
PF [arg] 


PH Page header {9.2} 
.PH [arg] 


PM Proprietary Marking {9.15} 
.PM [code] 


PX * Page-header user exit {9.12} 
.PX 


R Return to regular (roman) font (end underlining in nroff) 
{12.1} 
.R 


RB Roman/Bold {12.1} 
-RB [Roman-arg] [bold-arg] [Roman] [bold] [Roman] 


9—108 Programmer's Guide: CTIX Supplement 


RD 


RF 


RI 


RL 


TC 


TE 


TH 


[bold] 


Read insertion from terminal 12.11} 
.RD [prompt] [diversion] [string] 


Reference end {11.2} 
.RF 


Roman/Italic {12.1} 
.RI [Roman-arg] [italic-arg] [Roman] [italic] [Roman] 
[italic] 


Reference list start €5.3.3.5} 
-RL [text-indent] [1] 


Produce Reference Page {11.4} 
.RP [arg] [arg] 


Reference start {11.2} 
-RS [string-name] 


Set troff point size and vertical spacing €12.9} 
.S [size] [spacing] 


Set adjustment (right-margin justification) default €12.2} 
.SA [arg] 


Signature line {6.11.1} 
SG [arg] [1] 


Skip pages (12.7} 

SK [pages] 

Make a string smaller {12.9} 
.SM string] [string2] [string3] 
Space vertically {12.6} 

.SP [lines] 


Table title {7.5} 
.TB [title] [override] [flag] 


Table of contents {10.1} 
-TC [slevel] [spacing] [tlevel] [tab] [head1] [head2] [head3] 
[head4] [head] 


Table end {7.3} 
.TE 


Table header {7.3} 
.TH [N] 
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TL Title of memorandum {6.1} 
-TL [charging-case] [filing-case] 
™ Technical Memorandum number(s) {6.3} 
-TM [number] ... 
TP * Top-of-page macro {9.12} 
.TP 
TS Table start {7.3} 
-TS [H] 
TX * Table-of-contents user exit £10.13 
.TX 
TY*  Table-of-contents user exit (suppresses ““CONTENTS’’) 
{10.1} 
TY 
VL Variable-item list start {5.3.3.6} 
.VL text-indent [mark-indent] [1] 
VM Vertical margins {9.14} 
.VM [top] [bottom] 
WC Width Control {12.4} 
.WC [format] 
ll. Strings 


The following is an alphabetical list of string names used by MM, giv- 
ing for each a brief description, section reference, and initial (default) 
value(s). See {1.4} for notes on setting and referencing strings. 


BU 


Ci 


EM 


Bullet 3.7} 

nroff: ® 

troff: @ 

Table-of-contents indent list, up to seven args for heading 
levels (must be scaled) {10.1} 


Date (current date, unless overridden) {6.7.1} 
Month day, year (e.g., ) 


Em dash string, produces an em dash in troff and a double 
hyphen in nroff {3.8}. 


Footnote numberer {8.1} 
nroff: \u\\n+(:p\d 
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troff: \v’—.4m’\s-3\\n+ (:p\sO\v’.4m’ 


HF Heading font list, up to seven codes for heading levels 1 
through 7 {4.2.2.4.1} 
3.3222 2 2 (levels 1 and 2 bold, 3-7 underlined in nroff, 
and italic in troff) 


HP Heading point size list, up to seven codes for heading levels 
1 through 7 €4.2.2.4.3} 


Le Title for LIST OF EQUATIONS {7.6} 


Lf Title for LIST OF FIGURES {7.6} 
Lt Title for LIST OF TABLES {7.6} 
Lx Title for LIST OF EXHIBITS {7.6} 


RE SCCS Release and Level of MM {12.3} 
Release. Level (e.g., 15.130) 


Rf Reference numberer {11.1} 
Rp Title for References {11.4} 
Tm Trademark string; places the letters ““TM” one half-line 


above the text that it follows {3.9}. 
Seven accent strings are also available {12.10}. 


If the released-paper style is used, then, in addition to the above 
strings, certain BTL location codes are defined as strings; these loca- 
tion strings are needed only until the .MT macro is called {6.8}. 
Currently, the following are recognized: AK, AL, ALF, CB, CH, 
CP, DR, FJ, HL, HO, HOH, HP, IH, IN, INH, IW, MH, MV, 
PY, RD, RR, WB, WH, and WV. 


ill. Number Registers 


This section provides an alphabetical list of register names, giving for 
each a brief description, section reference, initial (default) value, and 
the legal range of values (where [m:n] means values from m to n 
inclusive). 


Any register having a single-character name can be set from the com- 
mand line. An asterisk attached to a register name indicates that that 
register can be set only from the command line or before the MM 
macro definitions are read by the formatter 2.4, 2.5}. See {1.4} 
for notes on setting and referencing registers. 
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cl 


Cp 


Handles preprinted forms and the Bell System logo 2.4} 
0, [0:2] 


Inhibits printing of author’s location, department, room, 
and extension in the ‘from’ portion of a memorandum 
{6.2} 

1, [0:1] 

Copy type (Original, DRAFT, etc.) {2.4} 

0 (Original), [0:4] 


Contents level (i.e., level of headings saved for table of con- 
tents) 4.4} 

2, [0:7] 

Placement of List of Figures, etc. {10.1} 

1 (on separate pages), [0:1] 

Debug flag {2.4} 

0, [0:1] 

Display eject register for floating dislays {7.2} 

0, [0:1] 

Display format register for floating displays {7.2} 
5, [0:5] 

Static display pre- and post-space {7.1} 

1, [0:1] 

Controls font of the Subject/Date/From fields {2.4} 
0 (nroff) 1 (troff), [0:1] 

Equation counter, used by .EC macro {7.5} 

0, [0:?], incremented by 1 for each .EC call. 
Page-ejection flag for headings {4.2.2.1} 

0 (no eject), [0:7] 

Equation label placement {7.4} 

0 (right-adjusted), [0:1] 

Exhibit counter, used by .EX macro {7.5} 

0, [0:?], incremented by 1 for each .EX call. 


Figure counter, used by .FG macro {7.5} 
0, [0:2], incremented by 1 for each .FG call. 


Footnote space (i.e., spacing between footnotes) {8.4} 
1, [0:7] 
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H1-H7 


Hb 


Hu 


Hy 


Lt 


Heading counters for levels 1-7 {4.2.2.5} 

0, [0:2], incremented by .H of corresponding level or .HU if 
at level given by register Hu. H2-H7 are reset to 0 by any 
heading at a lower-numbered level. 


Heading break level (after .H and .HU) {4.2.2.2} 
2, [0:7] 

Heading centering level for .H and .HU {4.2.2.3} 
0 (no centered headings), [0:7] 


Heading temporary indent (after .H and .HU) {4.2.2.2} 
1 (indent as paragraph), [0:2] 


2 (space only after .H 1 and .H 2), [0:7] 


Heading type (for .H: single or concatenated numbers) 
{4.2.2.5} 
0 (concatenated numbers: 1.1.1, etc.), [0:1] 


Heading level for unnumbered heading (.HU) {4.3} 
2 (.HU at the same level as .H 2), [0:7] 


Hyphenation control for body of document {3.4} 
0 (automatic hyphenation off), [0:1] 


Length of page {2.4} 
66, [20:2] (11i, [2i:?] in troff)?? 


List of Equations {7.6} 

O (list not produced) [0:1] 

List of Figures {7.6} 

1 (list produced) [0:1] 

List indent {5.3.3.1} 

6 (nroff) S (troff), [0:2] 

List spacing between items by level {5.3.3.1} 
6 (spacing between all levels) [0:6] 


List of Tables {7.6} 
1 (list produced) [0:1] 


22. For nroff, these values are unscaled numbers representing lines or character 
positions; for troff, these values must be scaled. 
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List of Exhibits £7.6} 

1 (list produced) [0:1] 

Numbering style {2.4} 

0, [0:5] 

Numbering style for paragraphs €4.1} 

0 (unnumbered) [0:1] 

Offset of page {2.4} 

.75i, [0:2] (0.5i, [0i:?] in troff)?* 

Table of Contents page numbering style {10.1} 
0 (lower-case Roman), [0:1] 


Figure caption style {7.5} 
0 (period separator), [0:1] 


Page number, managed by MM {2.4} 
0, [0:7] 

Paragraph indent {4.1} 

5 (nroff) 3 (troff), [0:7] 


Paragraph spacing {4.1} 
1 (one blank space between paragraphs), [0:?] 


Paragraph type {4.1} 
0 (paragraphs always left-justified), [0:2] 


“PRIVATE” header {£9.16} 

0 (not printed), [0:2] 

Reference counter, used by .RS macro {11.1} 
0, [0:2], incremented by 1 for each .RS call. 


Troff default point size {2.4} 
10, [6:36] 


Standard indent for displays {7.1} 
5 (nroff) 3 (troff), [0:2] 


Type of nroff output device {2.4} 
0, [0:2] 


Table counter, used by .TB macro {7.5} 
0, [0:2], incremented by 1 for each .TB call. 


Underlining style (nroff) for .H and .HU {2.4} 
0 (continuous underline when possible), [0:1] 


Width of page (line and title length) {2.4} 
6i, {10:1365] (6i, [2i:7.54i] in rroff)* 
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Using the —ms Macros with Troff and Nroff 


Abstract 


This document describes a set of easy-to-use macros for preparing 
documents on the UNIX system. Documents may be produced on 
either the phototypesetter or a on a computer terminal, without 
changing the input. 


The macros provide facilities for paragraphs, sections (optionally with 
automatic numbering), page titles, footnotes, equations, tables, two- 
column format, and cover pages for papers. 


This memo includes, as an appendix, the text of the “‘Guide to 
Preparing Documents with —ms’”’ which contains additional examples 
of features of —ms. 


This manual is a revision of, and replaces, ‘“Typing Documents on 
UNIX,”’ dated November 22, 1974. 


Introduction 


This memorandum describes a package of commands to produce 
papers using the troff and nroff formatting programs on the UNIX sys- 
tem. As with other roff-derived programs, text is prepared inter- 
spersed with formatting commands. However, this package, which 
itself is written in troff commands, provides higher-level commands 
than those provided with the basic troff program. The commands 
available in this package are listed in Appendix A. 


Source: M. E. Lesk, Typing Documents on the UNIX System: Using the —-ms Macros 
with Troff and Nroff (Murray Hill, N.J.: Bell Laboratories, 1978). 
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Text 


Type normally, except that instead of indenting for paragraphs, place 
a line reading ‘.PP’ before each paragraph. This will produce 
indenting and extra space. 


Alternatively, the command .LP that was used here will produce a 
left-aligned (block) paragraph. The paragraph spacing can be 
changed: see below under ‘‘Registers.”” 


Beginning 


For a document with a paper-type cover sheet, the input should start 
as follows: 


[optional overall format .RP — see below] 
.TL 

Title of document (one or more lines) 
AU 

Author(s) (may also be several lines) 


Author’s institution(s) 

.AB 

Abstract; to be placed on the cover sheet of a paper. 
Line length is 5/6 of normal; use .ll here to change. 
.AE (abstract end) 

text ... (begins with .PP, which see) 


To omit some of the standard headings (e.g. no abstract, or no 
author’s institution) just omit the corresponding fields and command 
lines. The word ABSTRACT can be suppressed by writing ““.AB no” 
for ‘“. AB’. Several interspersed .AU and .AT lines can be used for 
multiple authors. The headings are not compulsory: beginning with a 
.PP command is perfectly OK and will just start printing an ordinary 
paragraph. 
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CAUTION 


You can’t just begin a document with a line of text. Some 
—ms command must precede any text input. When in doubt, 
use .LP to get proper initialization, although any of the com- 
mands .PP, .LP, .TL, .SH, .NH is good enough. Figure 1 
shows the legal arrangement of commands at the start of a 
document. 


Cover Sheets and First Pages 


The first line of a document signals the general format of the first 
page. In particular, if it is ‘““.RP’’ a cover sheet with title and abstract 
is prepared. The default format is useful for scanning drafts. 


In general —ms is arranged so that only one form of a document need 
be stored, containing all information; the first command gives the 
format, and unnecessary items for that format are ignored. 


CAUTION 


Don’t put extraneous material between the .TL and .AE com- 
mands. Processing of the titling items is special, and other 
data placed in them may not behave as you expect. Don’t for- 
get that some —ms command must precede any input text. 


Page Headings 


The —ms macros, by default, will print a page heading containing a 
page number (if greater than 1). A default page footer is provided 
only in nroff, where the date is used. The user can make minor 
adjustments to the page headings/footings by redefining the strings 
LH, CH, and RH which are the left, center and right portions of the 
page headings, respectively; and the strings LF, CF, and RF, which 
are the left, center and right portions of the page footer. For more 
complex formats, the user can redefine the macros PT and BT, which 
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are invoked respectively at the top and bottom of each page. The 
margins (taken from registers HM and FM for the top and bottom 
margin respectively) are normally 1 inch; the page header/footer are 
in the middle of that space. The user who redefines these macros 
should be careful not to change parameters such as point size or font 
without resetting them to default values. 


Multi-column Formats 


If you place the command ‘.2C” in your document, the document 
will be printed in double column format beginning at that point. This 
feature is not too useful in computer terminal output, but is often 
desirable on the typesetter. The command “‘.1C” will go back to 
one-column format and also skip to a new page. The ‘*.2C’? com- 
mand is actually a special case of the command 


.MC [column width [gutter width]] 


which makes multiple columns with the specified column and gutter 
width; as many columns as will fit across the page are used. Thus tri- 
ple, quadruple, ... column pages can be printed. Whenever the 
number of columns is changed (except going from full width to some 
larger number of columns) a new page is started. 


Headings 


To produce a special heading, there are two commands. If you type 


.NH 
type section heading here 
may be several lines 


you will get automatically numbered section headings (1, 2, 3, ...), in 
boldface. For example, 


.NH 
Care and Feeding of Department Heads 


produces 
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1. Care and Feeding of Department Heads 
Alternatively, 


.SH 
Care and Feeding of Directors 


will print the heading with no number added: 
Care and Feeding of Directors 


Every section heading, of either type, should be followed by a para- 
graph beginning with .PP or .LP, indicating the end of the heading. 
Headings may contain more than one line of text. 


The .NH command also supports more complex numbering schemes. 
If a numerical argument is given, it is taken to be a “level’” number 
and an appropriate sub-section number is generated. Larger level 
numbers indicate deeper sub-sections, as in this example: 


.NH 

Erie-Lackawanna 

.NH 2 

Morris and Essex Division 
.NH 3 

Gladstone Branch 

.NH 3 

Montclair Branch 

.NH 2 

Boonton Line 


generates: 


2. Erie-Lackawanna 

2.1 Morris and Essex Division 
2.1.1 Gladstone Branch 

2.1.2 Montclair Branch 

2.2 Boonton Line 


An explicit ““.NH 0” will reset the numbering of level 1 to one, as 
here: 


.NH 0 
Penn Central 


1. Penn Central 
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Indented Paragraphs 


(Paragraphs with hanging numbers, e.g. references.) The sequence 


IP [1] 

Text for first paragraph, typed 
normally for as long as you would 
like on as many lines as needed. 
LIP {2] 

Text for second paragraph, ... 


produces 


[1] Text for first paragraph, typed normally for as long as you 
would like on as many lines as needed. 


[2] Text for second paragraph. ... 


A series of indented paragraphs may be followed by an ordinary para- 


graph beginning with .PP or .LP, depending on whether you wish 
indenting or nat. The command .LP was used here. 


More sophisticated uses of .ITP are also possible. If the label is omit- 
ted, for exaniple. 2 plair block indent is produced. 


oll? 

This material sill 

just be turned into a 

block indent suitable for quotations or 
such matter. 


.LP 


will produce 
This materia wil just be turned into a block indent suitable for 
quotations or such matter. 


If a non-standard amount of indenting is required, it may be specified 
after the laber it character positions) and will remain in effect until 
the next .PP or .LP. hus, the general form of the .IP command 
contains two additional tields: the label and the indenting length. For 
example, 
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.IP first: 9 

Notice the longer label, requiring larger 
indenting for these paragraphs. 

.IP second: 

And so forth. 

.LP 


produces this: 


first: Notice the longer label, requiring larger indenting for these 
paragraphs. 


second: And so forth. 


It is also possible to produce multiple nested indents; the command 
.RS indicates that the next .IP starts from the current indentation 
level. Each .RE will eat up one level of indenting so you should bal- 
ance .RS and .RE commands. The .RS command should be thought 
of as ‘move right’? and the .RE command as “‘move left’. As an 
example 

JP 1. 

Bell Laboratories 

.RS 

AIP 1.1 

Murray Hill 

AP 1.2 

Holmdel 

AP 1.3 

Whippany 

-RS 


AP 1.3.1 
Madison 


Chester 
.RE 
.LP 


will result in 

1. Bell Laboratories 
1.1 Murray Hill 
1.2. Holmdel 
1.3. Whippany 
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1.3.1 Madison 
1.4. Chester 


All of these variations on .LP leave the right margin untouched. 
Sometimes, for purposes such as setting off a quotation, a paragraph 
indented on both right and left is required. 


A single paragraph like this is obtained by preceding it 
with .QP. More complicated material (several para- 
graphs) should be bracketed with .QS and .QE. 


Emphasis 


To get itulics (on the typesetter) or underlining (on the terminal) say 


I 
as much text as you want 
can be typed here 


AR 


as Was done for these three words. The .R command restores the nor- 
mai cusuaily Roman) font. If only one word is to be italicized, it 
muy be just given on the line with the .I command, 


PE word 


and in this case no .R is needed to restore the previous font. Bold- 
face con tx: produced by 


B 
‘ext to be set in boldface 
oes here 


.R 


1 
1 
au 

o 


and also will be underlined on the terminal or line printer. As with 
I, a singie word can be placed in boldface by placing it on the same 
line as the .B command. 


A few size changes can be specified similarly with the commands .LG 


(make larger), .SM (make smaller), and .NL (return to normal size). 
The size change is two points; the commands may be repeated for 
increased etfect (here one .NL canceled two .SM commands). 


If actual underlining as opposed to italicizing is required on the 
typesetter, the command 


UL. word 


10--8 Programmer's Guide: CTIX Supplement 


will underline a word. There is no way to underline multiple words 
on the typesetter. 


Footnotes 


Material placed between lines with the commands .FS (footnote) and 
.FE (footnote end) will be collected, remembered, and finally placed 
at the bottom of the current page*. By default, footnotes are 11/12th 
the length of normal text, but this can be changed using the FL regis- 
ter (see below). 


Displays and Tables 


To prepare displays of lines, such as tables, in which the lines should 
not be re-arranged, enclose them in the commands .DS and .DE 


.DS 

table lines, like the 
examples here, are placed 
between .DS and .DE 
.DE 


By default, lines between .DS and .DE are indented and left- 
adjusted. You can also center lines, or retain the left margin. Lines 
bracketed by .DS C and .DE commands are centered (and not re- 
arranged); lines bracketed by .DS L and .DE are left-adjusted, not 
indented, and not re-arranged. A plain .DS is equivalent to .DS I, 
which indents and left-adjusts. Thus, 


these lines were preceded 
by .DS C and followed by 


a .DE command; 
whereas 


* Like this. 
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these lines were preceded 
by .DS L and followed by 
a .DE command. 


Note that .DS C centers each line; there is a variant .DS B that 
makes the display into a left-adjusted block of text, and then centers 
that entire block. Normally a display is kept together, on one page. 
If you wish to have a long display which may be split across page 
boundaries, use .CD, .LD, or .ID in place of the commands .DS C, 
.DS L, or .DS I respectively. An extra argument to the .DS I or .DS 
command is taken as an amount to indent. Note: it is tempting to 
assume that .DS R will right adjust lines, but it doesn’t work. 


Boxing Words or Lines 


To draw rectangular boxes around words the command 
.BX word 


will print lw [word] as shown. The eee will not be neat on a terminal, 


Longer pieces of text may be boted by enclosing them with .B1 
and .B2: 
.Bl 
text... 
.B2 
as has been done here. 


Keeping Blocks Together 


If you wish to keep a table or other block of lines together on a page, 
there are ‘‘keep - release’? commands. If a block of lines preceded by 
.KS and followed by .KE does not fit on the remainder of the current 
page, it will begin on a new page. Lines bracketed by .DS and .DE 
commands are automatically kept together this way. There is also a 
“keep floating’’ command: if the block to be kept together is pre- 
ceded by .KF instead of .KS and does not fit on the current page, it 
will be moved down through the text until the top of the next page. 
Thus, no large blank space will be introduced in the document. 
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Nroff/Troff Commands 


Among the useful commands from the basic formatting programs are 
the following. They all work with both typesetter and computer ter- 
minal output: 


.bp begin new page. 
.br “‘break’’, stop running text from line to line. 
.spn___ insert n blank lines. 


na don’t adjust right margins. 


Date 


By default, documents produced on computer terminals have the date 
at the bottom of each page; documents produced on the typesetter 
don’t. To force the date, say ‘‘..DA’’. To force no date, say ‘“‘.ND”’. 
To lie about the date, say ‘““.DA July 4, 1776” which puts the speci- 
fied date at the bottom of each page. The command 


.ND May 8, 1945 


in ".RP" format places the specified date on the cover sheet and 
nowhere else. Place this line before the title. 


Signature Line 


‘You can obtain a signature line by placing the command .SG in the 
document. The authors’ names will be output in place of the .SG 
line. An argument to .SG is used as a typing identification line, and 
placed after the signatures. The .SG command is ignored in released 
paper format. 
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Registers 


Certain of the registers used by —ms can be altered to change default 
settings. They should be changed with .nr commands, as with 


.nr PS 9 


to make the default point size 9 point. 
immediately, the normal troff command should be used in addition to 
changing the number register. 


If the effect is needed 


Register _ Defines Takes Effect Default_ 
PS point size next para. 10 
VS __ line spacing next para. 12 pts 
LL line length next para. 6" 
LT title length next para. 6"' 
PD para. spacing next para. 0.3 VS 
PI para. indent next para. 5 ens 
FL footnote length next FS 11/12 LL 
CW column width next 2C TAS LL 
GW intercolumn gap next 2C 1/15 LL 
PO page offset next page 26/27'" 
HM top margin next page We 
FM _ bottom margin next page 1’ 


You may also alter the strings LH, CH, and RH which are the left, 
center, and right headings respectively; and similarly LF, CF, and RF 
which are strings in the page footer. The page number on output is 
taken from register PN, to permit changing its output style. For 
more complicated headers and footers the macros PT and BT can be 
redefined, as explained earlier. 


Accents 


To simplify typing certain foreign words, strings representing common 
accent marks are defined. They precede the letter over which the 
mark is to appear. Here are the strings: 
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Input Output . Input Output 


\*'e é \*"a a 
\ee é \*Ce € 
Vu ii \*cc ¢ 
XP te é€ 


Use 


After your document is prepared and stored on a file, you can print it 
on a terminal with the command* 


nroff —ms file 
and you can print it on the typesetter with the command 


troff —ms file 


(many options are possible). In each case, if your document is stored 
in several files, just list all the filenames where we have used “‘file’’. 
If equations or tables are used, egn and/or tbl must be invoked as 
preprocessors. 


References and Further Study 


If you have to do Greek or mathematics, see egn [1] for equation set- 
ting. To aid eqn users, —ms provides definitions of .EQ and .EN 
which normally center the equation and set it off slightly. An argu- 
ment on .EQ is taken to be an equation number and placed in the 
right margin near the equation. In addition, there are three special 
arguments to EQ: the letters C, I, and L indicate centered (default), 
indented, and left adjusted equations, respectively. If there is both a 
format argument and an equation number, give the format argument 
first, as in 


.EQ L (1.3a) 


* 


If .2C was used, pipe the nroff output through col; make the first line of the 
input **.pi /usr/bin/col.”” 
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for a left-adjusted equation numbered (1.3a). 


Similarly, the macros .TS and .TE are defined to separate tables (see 
[2]) from text with a little space. A very long table with a heading 
may be broken across pages by beginning it with .TS H instead of 
.TS, and placing the line .TH in the table data after the heading. If 
the table has no heading repeated from page to page, just use the 
ordinary .TS and .TE macros. 


To learn more about troff see [3] for a general introduction, and [4] 
for the full details (experts only). Information on related UNIX com- 
mands is in [5]. For jobs that do not seem well-adapted to ~ms, con- 
sider other macro packages. It is often far easier to write a specific 
macro packages for such tasks as imitating particular journals than to 
try to adapt —ms. 
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Appendix A: List of Commands 


1C_ Return to single column format. 
2C Start double column format. 
AB Begin abstract. 

AE End abstract. 

Al Specify author’s institution. 

AU Specify author. 

B_ Begin boldface. 

DA Provide the date on each page. 
DE End display. 


DS Start display (also CD, LD, ID). 


EN End equation. 
EQ Begin equation. 
FE End footnote. 
FS Begin footnote. 


I Begin italics. 


IP Begin indented paragraph. 
KE Release keep. 

KF Begin floating keep. 

KS Start keep. 


LG Increase type size. 
LP Left aligned block paragraph. 


ND Change or cancel date. 
NH Specify numbered heading. 
NL Return to normal type size. 
PP Begin paragraph. 


R_ Return to regular font (usually Roman). 
RE End one level of relative indenting. 

RP Use released paper format. 

RS Relative indent increased one level. 

SG Insert signature line. 

SH Specify section heading. 

SM Change to smaller type size. 

TL Specify title. 


UL Underline one word. 


Register Names 


The following register names are used by —ms internally. Independent use of these 


names in one’s own macros may produce incorrect output. 


Note that no lower 


case letters are used in any —ms internal name. 


Number registers used in —ms 


: DW GW HM IQ LL NA OJ PO T. TV 
#T EF Hl HT IR LT NC PD PQ TB VS 
1T FL H3 IK KI MM NF PF PX TD YE 
AV FM H4 IM Ll MN NS PI RO TN YY 
CW FP HS IP LE MO Ol PN ST TQ ZN 
String registers used in -ms 
: AS CB DW EZ I KF MR RI RT TL 
5 AB cc DY FA 1 KQ ND R2 So ™™ 
as AE CD El FE 2 KS NH R3 S1 TQ 
~ Al CF E2 FJ B LB NL R4 S2 TS 
AU CH £3 FK 14 LD NP RS SG TT 
4 B CM E4 FN i LG OD RC SH UL 
1¢ BG CS ES FO ID LP OK RE SM _ WB 
2C BT CT EE FQ IE ME PP RF SN WH 
Al Cc D EL FS IM MF PT RH SY WT 
A2 Ci DA EM FV IP MH PY RP TA XD 
A3 C2 DE EN FY IZ MN QF RQ TE XF 
A4 CA DS EQ HO KE MO R RS TH XK 
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TL 


Al 


NH, SH 


PP, LP 


text ... 


Figure 10-1. Order of Commands in Input 
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A Guide to Preparing Documents with —ms 


Commands for a TM 


Input: 


.TM 1978-5b3 99999 99999-11 

.ND April 1, 1976 

.TL 

The Role of the Allen Wrench in Modern Electronics 
.AU "MH 2G-111" 2345 

J. Q. Pencilpusher 

.AU "MH 1K-222" 5432 

X. Y. Hardwired 


This abstract should be short enough to 
fit on a single page cover sheet. 

It must attract the reader into sending for 
the complete memorandum. 

AE 

.CS 10212567 

.NH 

Introduction. 

.PP 

Now the first paragraph of actual text ... 


Last line of text. 
SG MH-1234-JOP/X YH-unix 


.NH 
References ... 


Commands not needed in a particular format are ignored. 


Using the —ms Macros 


10—17 


Output: 


® Bell Laboratories Cover Sheet for TM 
This information is for employees of Beli Laboratories. (GEI 13.9-3} 
Title-The Role of the Allen Wrench Date- April 1, 1976 

in Modern Electronics 
TM- 1978-5b3 
Other Keywords- Tools 
Design 

Author Location Ext. Charging Case- 99999 


J. Q. Pencilpusher MH 2G-111 2345 Filing Case- 99999a 
X. Y. Hardwired MH 1K-222 5432 


ABSTRACT 


This abstract should be short enough to fit on a single 
page cover sheet. It must attract the reader into sending 
for the complete memorandum. 


Pages Text 10 Other 2 Total 12 
No. Figures 5 No. Tables 6 No. Refs. 7 
E-1932-U (6-73) SEE REVERSE SIDE FOR DISTRIBUTION LIST 
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A Released Paper with Mathematics 


Input: 


.EQ 

delim $$ 

.EN 

.RP 

... (as for a TM) 

.CS 10212567 

.NH 

Introduction 

.PP 

The solution to the torque handle equation 
.EQ (1) 

sum from 0 to inf F (x subi) = G(x) 
.EN 


is found with the transformation $ x = rho over theta $ 
where $ rho = G prime (x) $ and $theta$ is derived ... 


Output: 


The Role of the Allen Wrench 
in Modern Electronics 


J. Q. Pencilpusher 
X.Y. Hardwired 


Bell Laboratories 
Murray Hill, New Jersey 07974 


ABSTRACT 


into sending for the complete memorandum. 


Mas 1, 1976 


-————_ 


This abstract should be short enough to fit on a 
single page cover sheet. It must attract the reader 
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The Role of the Allen Wrench 
in Modern Electronics 


J. Q. Pencilpusher 
X. Y. Hardwired 


Bell Laboratories 
Murray Hill, New Jersey 07974 


1. Introduction 
The solution to the torque handle equation 


SF (s))=G) (1) 


is found with the transformation oar where p=G'(x) 


and @ is derived from well-known principles. 
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An Internal Memorandum 


Input: 


.IM 

.ND January 24, 1956 

.TL 

The 1956 Consent Decree 

.AU 

Able, Baker & 

Charley, Attys. 

.PP 

Plaintiff, United States of America, having filed 
its complaint herein on January 14, 1949; the 
defendants having appeared and filed their... 


Output: 
Bell Laboratories 
Subject: The 1956 Consent Decree date: January 24, 1956 


from: Able, Baker & 
Charley, Attys. 


Plaintiff, United States of America, having filed its complaint herein on 
January 14, 1949; the defendants having appeared and filed their answer to 
such complaint denying the substantive allegations thereof; and the parties, 
by their attorneys, having severally consented to the entry of this Final 
Judgment without trial or adjudication of any issues of fact or law herein 
and without this Final Judgment constituting any evidence or admission by 
any party in respect of any such issues; 


Now, therefore before any testimony has been taken herein, and without 
trial or adjudication of any issue of fact or law herein, and upon the con- 
sent of all parties hereto, it is hereby 


Ordered, adjudged and decreed as follows: 
I. [Sherman Act] 


This Court has jurisdiction of the subject matter herein and of all the 
parties hereto. The complaint states a claim upon which relief may be 
granted 


| 


Other formats possible (specify before .TL) are: .MR (‘‘memo for 
record’), .MF (‘“‘memo for file’), .EG (‘“‘engineer’s notes’) and .TR 
(Computing Science Tech. Report). 
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Headings 


Input: 


.NH SH 
Introduction. Appendix I 
.PP .PP 

text text text text text text 


Output: 


1. Introduction Appendix I 
text text text text text text 


A Simple List 


Input: 


IP 1. 

J. Pencilpusher and X. Hardwired, 
I 

A New Kind of Set Screw, 

.R 

Proc. IEEE 

.B75 

(1976), 23-255. 

IP 2. 

H. Nails and R. Irons, 

J 

Fasteners for Printed Circuit Boards, 
.R 

Proc. ASME 

.B 23 

(1974), 23-24. 

.LP (terminates list) 


Output: 


1. J. Pencilpusher and X. Hardwired, A New Kind of Set Screw, 
Proc. IEEE 75 (1976), 23-255. 


2. H. Nails and R. Irons, Fasteners for Printed Circuit Boards, 
Proc. ASME 23 (1974), 23-24. 
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Displays 


Input: 


text text text text text text 
._DS 

and now 

for something 

completely different 

.DE 

text text text text text text 


Output: 


hoboken harrison newark roseville avenue grove street east orange 
brick church orange highland avenue mountain station 


and now 
for something 
completely different 


murray hill berkeley heights gillette stirling millington lyons basking 
ridge bernardsville far hills peapack gladstone 


Options: .DS L: left-adjust; .DS C: line-by-line center; .DS B: make 
block, then center. 


Footnotes 


Input: 


Among the most important occupants 

of the workbench are the long-nosed pliers. 
Without these basic tools* 

LFS 

* As first shown by Tiger & Leopard (1975). 
.FE 

few assemblies could be completed. They may 
lack the popular appeal of the sledgehammer 


Output: 


Among the most important occupants of the workbench are the long- 
nosed pliers. Without these basic tools* few assemblies could be com- 
pleted. They may lack the popular appeal of the sledgehammer 
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Multiple Indents 


Input: 


This is ordinary text to point out 
the margins of the page. 

JP 1. 

First level item 

.RS 

IP a) 

Second level. 

IP b) 

Continued here with another second 
Jevel item, but somewhat longer. 
.RE 

IP 2. 

Return to previous value of the 
indenting at this point. 

IP 3. 

Another 

line. 


Output: 
This is ordinary text to point out the margins of the page. 
i. First level item 

a) Second level. 


b) Continued here with another second level item, but some- 
what longer. 


ine) 


Return to previous value of the indenting at this point. 


3. Another line. 


* As first shown by Tiger & Leopard (1975). 
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Keeps 


Lines bracketed by the following commands are kept together, and 
will appear entirely on one page: 


.KS not moved 
._KE through text 
Double Column 


Input: 
TL 


The Declaration of Independence 


.2C 
.PP 


.KF may float 
-KE in text 


When in the course of human events, it becomes necessary for one 
people to dissolve the political bonds which have connected them with 
another, and to assume among the powers of the earth the separate 
and equal station to which the laws of Nature and of Nature’s God 
entitle them, a decent respect to the opinions of... 


Output: 


The Declaration of Independence 


When in the course of human 
events, it becomes necessary for one 
people to dissolve the political bonds 
which have connected them with 
another, and to assume among the 
powers of the earth the separate and 
equal station to which the laws of 
Nature and of Nature’s God entitle 
them, a decent respect to the opin- 
ions of mankind requires that they 


should declare the causes which 
impel them to the separation. 

We hold these truths to be self- 
evident, that all men are created 
equal, that they are endowed by their 
creator with certain unalienable 
rights, that among these are life, 
liberty, and the pursuit of happiness. 
That to secure these rights, govern- 
ments are instituted among men, 
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Equations 


Input: 


A displayed equation is marked 

with an equation number at the right margin 

by adding an argument to the EQ line: 

.EQ (1.3) 

x Sup 2 over a sup 2 ~=~ sqrt {pz sup 2 +qz+r} 
.EN 


Output: 


A displayed equation is marked with an equation number at the right 
margin by adding an argument to the EQ line: 


# a Vet taier (1.3) 


a 


i) 


Input: 


EQ I (2.2a) 

bold V bar sub nu~=“left [ pile {a above b above 
c } right ] + left [ matrix { col { A(11) above . 
above . } col { . above . above .} col {. above . 
above A(33) }} right ] cdot left [ pile € alpha 
above beta above gamma } right | 

Input: 


.EN 
11). 4 a 
i. es | (2.20) 
c .  . A(33)]} Jy 
EQ L 


F hat ( chi ) ~ mark = ~ | del V | sup 2 

.EN 

EQ L 

lineup =~ {left ( {partial V} over {partial x} right ) } sup 2 
+ { left ( {partial V} over {partial y} right ) } sup 2 
eed lambda -> inf 


Output: 
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Output: 


F(x) = | VV I? 


2 2 
Pog ae a) Le ho 
ox dy 


Input: 


$a dot $, $b dotdot$, $ xi tilde times y vec$: 


Output: 
a, b, €XY¥. 


See also the equations in the table example. 


Some Registers You Can Change 


Line length 
nr LL 7i 


Title length 
-or LT 7i 

Point size 
.nr PS 9 


Vertical spacing 
-nr VS 11 


Column width 
-nr CW 3i 


Intercolumn spacing 
.or GW .5i 


Margins — head and foot 
nr HM .75i 
snr FM .75i 


Paragraph indent 
wnr PI 2n 


Paragraph spacing 
nr PDO 


Page offset 
nr PO 0.5i 


Page heading 
.ds CH Appendix 
(center) 
.ds RH 7-25-76 
(right) 
.ds LH Private 
(left) 


Page footer 
.ds CF Draft 
.dsLF .. 
ds RE similar 


Page numbers 
nr % 3 
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Tables 


Input: Output: 


-TS (@ indicates a tab) AT&T Common Stock 
allbox; 

css 

cece 

nnn. 

AT&T Common Stock 
Year @ Price ® Dividend 
1971 © 41-54 ©$2.60 

2 @41-54 ®2.70 

3 ©46-55 ©2.87 * (first quarter only) 
4 @40-53 ©3.24 

5 @45-52 ©3.40 

6@51-59 ®.95* 

.TE 

* (first quarter only) 


The meanings of the key-letters describing the alignment of each 
entry are: 


c center n numerical 
r_ right-adjust a subcolumn 
1 left-adjust S spanned 


The global table options are center, expand, box, doublebox, allbox, 
tab (x) and linesize (). 


Input: 

-TS (with delim $$ on) 
doublebox, center; 

cc 


11. 
Name @ Definition 


“Sp 
Gamma ®$GAMMA (z) = int sub 0 sup inf \ 

t sup {z-1} e sup -t dt$ 
Sine @$sin (x) = 1 over 2i ( e sup ix - e sup -ix )$ 
Error ©$ roman erf (z) = 2 over sqrt pi \ 

int sub 0 sup ze sup {-t sup 2} dt$ 
Bessel @$ J sub 0 (z) = 1 over pi \ 

int sub 0 sup pi cos ( z sin theta ) d theta $ 
Zeta O$ zeta (s) = \ 
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sum from k=1 to inf k sup -s ~~( Res > 1)$ 


TE 
Output: 
Name Definition 
Gamma T)=forte ‘dt 
Sine sin(x)=s-(e#-e-*) 
Error erf(z)= vise "dt 
Bessel Jo(z)= * f,"coste sin@)dé 
Zeta Us)= Sk (Re s>1) 
k=) 
Usage 


Documents with just text: 
troff -ms files 
With equations only: 
eqn files | troff -ms 
With tables only: 
tbl files | troff -ms 
With both tables and equations: 
tbl files | eqn | troff -ms 
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Writing Papers with NROFF Using —me 


Introduction 


This document describes the text processing facilities available on the 
UNIX operating system via NROFF and the —-me macro package. It is 
assumed that the reader already is generally familiar with the UNIX 
operating system and a text editor such as ex. This is intended to be 
a casual introduction, and as such not all material is covered. In par- 
ticular, many variations and additional features of the -me macro 
package are not explained. For a complete discussion of this and 
other issues, see The —me Reference Manual and The NROFF/TROFF 
Reference Manual. 


NROFF, a computer program that runs on the UNIX operating system, 
reads an input file prepared by the user and outputs a formatted 
paper suitable for publication or framing. The input consists of text, 
or words to be printed, and requests, which give Instructions to the 
NROFF program telling how to format the printed copy. 


Section 1 describes the basics of text processing. Section 2 describes 
the basic requests. Section 3 introduces displays. Annotations, such 
as footnotes, are handled in section 4. The more complex requests 
which are not discussed in section 2 are covered in section 5. Finally, 
section 6 discusses things you will need to know if you want to typeset 
documents. If you are a novice, you probably won’t want to read 
beyond section 4 until you have tried some of the basic features out. 


When you have your raw text ready, call the NROFF formatter by typ- 
ing as a request to the UNIX shell: 


nroff —me —Ttype files 


Source: Eric P. Allman, Writing Papers with NROFF Using —me (Berkeley, CA: 
University of California, 1980). 
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where type describes the type of terminal you are outputting to. 
Common values are dte for a DTC 300s (daisy-wheel type) printer 
and Ipr for the line printer. If the -T flag is omitted, a “lowest com- 
mon denominator” terminal is assumed; this is good for previewing 
output on most terminals. A complete description of options to the 
NROFF command can be found in The NROFF/TROFF Reference 
Manual, 


The word argument is used in this manual to mean a word or number 
which appears on the same line as a request which modifies the mean- 
ing of that request. For example, the request 


.Sp 


spaces one line, but 
sp 4 


spaces four lines. The number 4 is an argument to the .sp request 
which says to space four lines instead of one. Arguments are 
separated from the request and from each other by spaces. 


1. Basics of Text Processing 


The primary function of NROFF is to collect words from input lines, 
fill output lines with those words, justify the right hand margin by 
inserting extra spaces in the line, and output the result. For example, 
the input: 


Now is the time 

for all good men 

to come to the aid 

of their party. 

Four score and seven 
years ago,... 


will be read, packed onto output lines, and justified to produce: 


Now is the time for all good men to come to the aid of their 
party. Four score and seven years ago,... 


Sometimes you may want to start a new output line even though the 
line you are on is not yet full; for example, at the end of a paragraph. 
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To do this you can cause a break, which starts a new output line. 
Some requests cause a break automatically, as do blank input lines 
and input lines beginning with a space. 


Not all input lines are text to be formatted. Some of the input lines 
are requests which describe how to format the text. Requests always 
have a period or an apostrophe (‘‘~”’) as the first character of the 
input line. 


The text formatter also does more complex things, such as automati- 
cally numbering pages, skipping over page folds, putting footnotes in 
the correct place, and so forth. 


I can offer you a few hints for preparing text for input to NROFF. 
First, keep the input lines short. Short input lines are easier to edit, 
and NROFF will pack words onto longer lines for you anyhow. In 
keeping with this, it is helpful to begin a new line after every period, 
comma, or phrase, since common corrections are to add or delete 
sentences or phrases. Second, do not put spaces at the end of lines, 
since this can sometimes confuse the NROFF processor. Third, do not 
hyphenate words at the end of lines (except words that should have 
hyphens in them, such as ‘‘mother-in-law’’); NROFF is smart enough 
to hyphenate words for you as needed, but is not smart enough to 
take hyphens out and join a word back together. Also, words such as 
“‘mother-in-law’’ should not be broken over a line, since then you will 
get a space where not wanted, such as ‘‘mother- in-law”. 


2. Basic Requests 
2.1 Paragraphs 


Paragraphs are begun by using the .pp request. For example, the 
input: 


-PP 

Now is the time for all good men 

to come to the aid of their party. 

Four score and seven years ago,... 


produces a blank line followed by an indented first line. The result 
is: 


Now is the time for all good men to come to the aid of their 
party. Four score and seven years ago,... 
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Notice that the sentences of the paragraphs must not begin with a 
space, since blank lines and lines beginning with spaces cause a break. 
For example, if I had typed: 


-PP 
Now is the time for all good men 

to come to the aid of their party. 
Four score and seven years ago,... 


The output would be: 


Now is the time for all good men 
to come to the aid of their party. Four score and seven years 
ago,... 


A new line begins after the word ‘‘men’’ because the second line 
began with a space character. 


There are many fancier types of paragraphs, which will be described 
later. 


2.2 Headers and Footers 


Arbitrary headers and footers can be put at the top and bottom of 
every page. Two requests of the form .he zitle and .fo title define the 
titles to put at the head and the foot of every page, respectively. The 
titles are called three-part titles, that is, there is a left-justified part, a 
centered part, and a right-justified part. To separate these three parts 
the first character of title (whatever it may be) is used as a delimiter. 
Any character may be used, but backslash and double quote marks 
should be avoided. The percent sign is replaced by the current page 
number whenever found in the title. For example, the input: 


che © °%" * 
.fo “Jane Jones ~ “My Book ~ 


results in the page number centered at the top of each page, “‘Jane 
Jones” in the lower left corner, and ‘“‘My Book”’ in the lower right 
corner. 
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2.3 Double Spacing 


NROFF will double space output text automatically if you use the 
request .Is 2, as is done in this section. You can revert to single 


spaced mode by typing .Is 1. 


2.4 Page Layout 


A number of requests allow you to change the way the printed copy 
looks, sometimes called the /ayout of the output page. Most of these 
requests adjust the placing of ‘“‘white space’’ (blank lines or spaces). 
In these explanations, characters in italics should be replaced with 
values you wish to use; bold characters represent characters which 
should actually be typed. 


The .bp request starts a new page. 


The request .sp N leaves N lines of blank space. N can be omitted 
(meaning skip a single line) or can be of the form Ni (for N inches) or 
Ne (for N centimeters). For example, the input: 


“sp 1.5i 
My thoughts on the subject 
a) 


leaves one and a half inches of space, followed by the line “‘My 
thoughts on the subject,’’ followed by a single blank line. 


The .in +N request changes the amount of white space on the left of 
the page (the indent). The argument N can be of the form +N (mean- 
ing leave N spaces more than you are already leaving), -N (meaning 
leave less than you do now), or just N (meaning leave exactly N 
spaces). N can be of the form Ni or Ne also. For example, the input: 


initial text 
.in § 
some text 
in +1i 
more text 
In —2c 
final text 


produces “‘some text’? indented exactly five spaces from the left 
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margin, “‘more text’’ indented five spaces plus one inch from the left 
margin (fifteen spaces on a pica typewriter), and “‘final text’’ indented 
five spaces plus one inch minus two centimeters from the margin. 
That is, the output 1s: 


initial text 
some text 
more text 
final text 


The .ti +N (temporary indent) request is used like .in +N when the 
indent should apply to one line only, after which it should revert to 
the previous indent. For example, the input: 


.in li 

ti 0 

Ware, James R. The Best of Confucius, 

Halcyon House, 1950. 

An excellent book containing translations of 

most of Confucius ~ most delightful sayings. 

A definite must for anyone interested in the early foundations 
of Chinese philosophy. 


produces: 


Ware, James R. The Best of Confucius, Halcyon House, 1950. An 
excellent book containing translations of most of Confu- 
cius’ most delightful sayings. A definite must for any- 
one interested in the early foundations of Chinese phi- 
losophy. 


Text lines can be centered by using the .ce request. The line after the 
.ce is centered (horizontally) on the page. To center more than one 
line, use .ce N (where N is the number of lines to center), followed by 
the N lines. If you want to center many lines but don’t want to count 
them, type: 


.ce 1000 
lines to center 
.ce 0 


The .ce 0 request tells NROFF to center zero more lines, in other 
words, stop centering. 


All of these requests cause a break; that is, they always start a new 
line. If you want to start a new line without performing any other 
action, use .br. 
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2.5 Underlining 


Text can be underlined using the .ul request. The .ul request causes 
the next input line to be underlined when output. You can underline 
multiple lines by stating a count of input lines to underline, followed 
by those lines (as with the .ce request). For example, the input: 


ul 2 
Notice that these two input lines 
are underlined. 


will underline those eight words in NROFF. (In TROFF they will be 
set in italics.) 


3. Displays 


Displays are sections of text to be set off from the body of the paper. 
Major quotes, tables, and figures are types of displays, as are all the 
examples used in this document. All displays except centered blocks 
are output single spaced. 


3.1 Major Quotes 


Major quotes are quotes which are several lines long, and hence are 
set in from the rest of the text without quote marks around them. 
These can be generated using the commands .(q and .)q to surround 
the quote. For example, the input: 


As Weizenbaum points out: 
-(q 
It is said that to explain is to explain away. 
This maxim is nowhere so well fulfilled 
as in the areas of computer programming,... 
)q 

generates as output: 


As Weizenbaum points out: 
It is said that to explain is to explain away. This maxim 


is nowhere so well fulfilled as in the areas of computer 
programming,... 
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3.2 Lists 


A list is an indented, single spaced, unfilled display. Lists should be 
used when the material to be printed should not be filled and justified 
like normal text, such as columns of figures or the examples used in 
this paper. Lists are surrounded by the requests .(1 and .)l. For 
example, type: 


Alternatives to avoid deadlock are: 

Al 

Lock in a specified order 

Detect deadlock and back out one process 
Lock all resources needed before proceeding 


I 
will produce: 
Alternatives to avoid deadlock are: 


Lock in a specified order 
Detect deadlock and back out one process 
Lock all resources needed before proceeding 


3.3 Keeps 


A keep is a display of lines which are kept on a single page if possible. 
An example of where you would use a keep might be a diagram. 
Keeps differ from lists in that lists may be broken over a page boun- 
dary whereas keeps will not. 


Blocks are the basic kind of keep. They begin with the request .(b 
and end with the request .)b. If there is not room on the current 
page for everything in the block, a new page is begun. This has the 
unpleasant effect of leaving blank space at the bottom of the page. 
When this is not appropriate, you can use the alternative, called float- 
ing keeps. 


Floating keeps move relative to the text. Hence, they are good for 
things which will be referred to by name, such as “‘See figure 3”. A 
floating keep will appear at the bottom of the current page if it will 
fit; otherwise, it will appear at the top of the next page. Floating 
keeps begin with the line .(z and end with the line .)z. For an exam- 
ple of a floating keep, see figure 1. The .hl request is used to draw a 
horizontal line so that the figure stands out from the text. 
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(Zz 

-hl 

Text of keep to be floated. 

.Sp 

.ce 

Figure 1. Example of a Floating Keep. 
-hi 


jz 


Figure 1. Example of a Floating Keep. 


3.4 Fancier Displays 


Keeps and lists are normally collected in nofill mode, so that they are 
good for tables and such. If you want a display in fill mode (for 
text), type .(1F (Throughout this section, comments applied to .(I 
also apply to .(b and .(z). This kind of display will be indented from 
both margins. For example, the input: 


UF 

And now boys and girls, 

a newer, bigger, better toy than ever before! 

Be the first on your block to have your own computer! 
Yes kids, you too can have one of these modern 

data processing devices. 

You too can produce beautifully formatted papers 
without even batting an eye! 


yl 


will be output as: 


And now boys and girls, a newer, bigger, better toy than 
ever before! Be the first on your block to have your own 
computer! Yes kids, you too can have one of these 
modern data processing devices. You too can produce 
beautifully formatted papers without even batting an eye! 


Lists and blocks are also normally indented (floating keeps are nor- 
mally left justified). To get a left-justified list, type .(1L. To get a 
list centered line-for-line, type .(1 C. For example, to get a filled, left 
justified list, enter: 
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(ILF 
text of block 
It 


The input: 
-( 


first line of unfilled display 
more lines 


yt 


produces the indented text: 


first line of unfilled display 
more lines 


Typing the character L after the .(1 request produces the left justified 
result: 


first line of unfilled display 
more lines 


Using C instead of L produces the line-at-a-time centered output: 


first line of unfilled display 
more lines 


Sometimes it may be that you want to center several lines as a group, 
rather than centering them one line at a time. To do this use cen- 
tered blocks, which are surrounded by the requests .(c and .)c. All 
the lines are centered as a unit, such that the longest line is centered 
and the rest are lined up around that line. Notice that lines do not 
move relative to each other using centered blocks, whereas they do 
using the C argument to keeps. 


Centered blocks are not keeps, and may be used in conjunction with 
keeps. For example, to center a group of lines as a unit and keep 
them on one page, use: 


(bL 


(c 
first line of unfilled display 
more lines 


Je 
.)b 


to produce: 
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first line of unfilled display 
more lines 


If the block requests (.(b and .)b) had been omitted the result would 
have been the same, but with no guarantee that the lines of the cen- 
tered block would have all been on one page. Note the use of the L 
argument to .(b; this causes the centered block to center within the 
entire line rather than within the line minus the indent. Also, the 
center requests must be nested inside the keep requests. 


4. Annotations 


There are a number of requests to save text for later printing. Foot- 
notes are printed at the bottom of the current page. Delayed text is 
intended to be a variant form of footnote; the text is printed only 
when explicitly called for, such as at the end of each chapter. /ndexes 
are a type of delayed text having a tag (usually the page number) 
attached to each entry after a row of dots. Indexes are also saved 
until called for explicitly. 


4.1 Footnotes 


Footnotes begin with the request .(f and end with the request .)f. 
The current footnote number is maintained automatically, and can be 
used by typing \**, to produce a footnote number!. The number is 
automatically incremented after every footnote. For example, the 
input: 


1. Like this. 
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(q 
A man who is not upright 


and at the same time is presumptuous; 

one who is not diligent and at the same time is ignorant; 
one who is untruthful and at the same time is incompetent; 
such men J do not count among acquaintances. \** 

.(f 

\**James R. Ware, 

.ul 

The Best of Confucius, 

Halcyon House, 1950. 


generates the result: 


A man who is not upright and at the same time is 
presumptuous; one who is not diligent and at the same time 
is ignorant; one who is untruthful and at the same time is 
incompetent; such men I do not count among acquain- 
tances.” 


It is important that the footnote appears inside the quote, so that you 
can be sure that the footnote will appear on the same page as the 


quote. 


4.2 Delayed Text 


Delayed text is very similar to a footnote except that it is printed 
when called for explicitly. This allows a list of references to appear 
(for example) at the end of each chapter, as is the convention in some 
disciplines. Use \*# on delayed text instead of \** as on footnotes. 


If you are using delayed text as your standard reference mechanism, 
you can still use footnotes, except that you may want to reference 


them with special characters* rather than numbers. 
p 


James R. Ware, The Best of Confucius, Halcyon House, 1950. Page 77. 


Such as an asterisk. 
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4.3 Indexes 


An ‘‘index’’ (actually more like a table of contents, since the entries 
are not sorted alphabetically) resembles delayed text, in that it is 
saved until called for. However, each entry has the page number (or 


some other tag) appended to the last line of the index entry after a 
row of dots. 


Index entries begin with the request .(x and end with .)x. The .)x 
request may have a argument, which is the value to print as the “page 
number’, It defaults to the current page number. If the page 
number given is an underscore (‘‘_”’) no page number or line of dots 
is printed at all. To get the line of dots without a page number, type 
.)x "" , which specifies an explicitly null page number. The .xp 
request prints the index. 


For example, the input: 


(x 

Sealing wax 

.)x 

(x 

Cabbages and kings 

JX 

(x 

Why the sea is boiling hot 

.)x 2.5a 

A(x 

Whether pigs have wings 

.)x ttt 

AX 

This is a terribly long index entry, such as might be used 
for a list of illustrations, tables, or figures; I expect it to 
take at least two lines. 

.)x 

.Xp 


generates: 


Sealing Wax .ilnd ieee sigs eee a as one A ee eas 9 
Cabbages and kings 

Why the sea is boiling hot .............cc cece eee ee cece ee eee ee eee een es 2.5a 
Whether pigs have Wings .............. 0. cies cece eee eee eee enna es 

This is a terribly long index entry, such as might be used for a 

list of illustrations, tables, or figures; I expect it to take at 

least tWo lines: jsecc oh bstclante ae elseiseeweatolinise lan Sig di foes e led ne 9 
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The .(x request may have a single character argument, specifying the 
“name” of the index; the normal index is x. Thus, several “‘indices’’ 
may be maintained simultaneously (such as a list of tables, table of 
contents, etc.). 


Notice that the index must be printed at the end of the paper, rather 
than at the beginning where it will probably appear (as a table of con- 
tents); the pages may have to be physically rearranged after printing. 


5. Fancier Features 


A iarge number of fancier requests exist, notably requests to provide 
other sorts of paragraphs, numbered sections of the form 1.2.3 (such 
as used in this document), and multicolumn output. 


5.1 More Paragraphs 


Paragraphs generally start with a blank line and with the first line 
indented. It is possible to get left-justified block-style paragraphs by 
using .lp instead of .pp, as demonstrated by the next paragraph. 


Sometimes you want to use paragraphs that have the body indented, 
and the first line exdented (opposite of indented) with a label. This 
can be done with the .ip request. A word specified on the same line 
as .ip is printed in the margin, and the body is lined up at a prespeci- 
fied position (normally five spaces). For example, the input: 


ip one 

This is the first paragraph. 

Notice how the first line 

of the resulting paragraph lines up 

with the other lines in the paragraph. 

.ip two 

And here we are at the second paragraph already. 
You may notice that the argument to .ip 
appears 

in the margin. 

Ip 

We can continue text... 


produces as output: 
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one ‘This is the first paragraph. Notice how the first line of the 
resulting paragraph lines up with the other lines in the para- 
graph. 


two And here we are at the second paragraph already. You may 
notice that the argument to .ip appears in the margin. 


We can continue text without starting a new indented paragraph by 
using the .lp request. 


If you have spaces in the label of a .ip request, you must use an 
‘“‘unpaddable space’’ instead of a regular space. This is typed as a 
backslash character (‘‘\’’) followed by a space. For example, to print 
the label ‘‘Part 1°’, enter: 


jp "Part\ 1" 


If a label of an indented paragraph (that is, the argument to .ip) is 
longer than the space allocated for the label, .ip will begin a new line 
after the label. For example, the input: 


.ip longlabel 

This paragraph had a long label. 

The first character of text on the first line 

will not line up with the text on second and subsequent lines, 
although they will line up with each other. 


will produce: 


longlabel 
This paragraph had a long label. The first character of text on 
the first line will not line up with the text on second and subse- 
quent lines, although they will line up with each other. 


It is possible to change the size of the label by using a second argu- 
ment which is the size of the label. For example, the above example 
could be done correctly by saying: 


.Ip longlabel 10 


which will make the paragraph indent 10 spaces for this paragraph 
only. If you have many paragraphs to indent all the same amount, 
use the number register ii. For example, to leave one inch of space 
for the label, type: 

ri li 
somewhere before the first call to .ip. Refer to the reference manual 
for more information. 
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If .ip is used with no argument at all no hanging tag will be printed. 
For example, the input: 


-ip [a] 

This is the first paragraph of the example. 

We have seen this sort of example before. 

Ip 

This paragraph is lined up with the previous paragraph, 
but it has no tag in the margin. 


produces as output: 


[a] This is the first paragraph of the example. We have seen this 
sort of example before. 


This paragraph is lined up with the previous paragraph, but it 
has no tag in the margin. 


A special case of .ip is .np, which automatically numbers paragraphs 
sequentially from 1. The numbering is reset at the next .pp, .Ip, or 
.sh (to be described in the next section) request. For example, the 
input: 


np 

This is the first point. 

np 

This is the second point. 

Points are just regular paragraphs 

which are given sequence numbers automatically 
by the .np request. 

-PP 

This paragraph will reset numbering by .np. 
np 

For example, 

we have reverted to numbering from one now. 


generates: 
(1) This is the first point. 


(2) This is the second point. Points are just regular paragraphs 
which are given sequence numbers automatically by the .np 
request. 


This paragraph will reset numbering by -np. 
(1) For example, we have reverted to numbering from one now. 


The .bu request gives lists of this sort that are identified with bullcts 
rather than numbers. The paragraphs are also crunched together. 
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For example, the input: 


bu 
One egg yolk 
bu 
One tablespoon cream or top milk 
bu 
Salt, cayenne, and lemon juice to taste 
-bu 
A generous two tablespoonfuls of butter 
produces’: 
e One egg yolk 
e One tablespoon cream or top milk 
e Salt, cayenne, and lemon juice to taste 
e A generous two tablespoonfuls of butter 


5.2 Section Headings 


Section numbers (such as the ones used in this document) can be 
automatically generated using the .sh request. You must tell .sh the 
depth of the section number and a section title. The depth specifies 
how many numbers are to appear (separated by decimal points) in the 
section number. For example, the section number 4.2.5 has a depth 
of three. 


Section numbers are incremented in a fairly intuitive fashion. If you 
add a number (increase the depth), the new number starts out at one. 
If you subtract section numbers (or keep the same number) the final 
number is incremented. For example, the input: 


3. By the way, if you put the first three ingredients in a a heavy, deep pan and 
whisk the ingredients madly over a medium flame (never taking your hand off 
the handle of the pot) until the mixture reaches the consistency of custard (just 
a minute or two), then mix in the butter off-heat, you will have a wonderful 
Hollandaise sauce. 
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.sh 1 "The Preprocessor" 
.sh 2 "Basic Concepts" 
sh 2 "Control Inputs" 
.sh 3 

.sh 3 

.sh 1 "Code Generation" 
.sh 3 


produces as output the result: 


. The Preprocessor 
. Basic Concepts 
. Control Inputs 


1 
2 

. Code Generation 
1 


You can specify the section number to begin by placing the section 
number after the section title, using spaces instead of dots. For 
example, the request: 


.sh 3 "Another section" 7 3 4 


will begin the section numbered 7.3.4; all subsequent .sh requests will 
number relative to this number. 


There are more complex features which will cause each section to be 
indented proportionally to the depth of the section. For example, if 
you enter: 


nr si N 


each section will be indented by an amount N. N must have a scaling 
factor attached, that is, it must be of the form Nx, where x is a char- 
acter telling what units N is in. Common values for x are i for inches, 
ce for centimeters, and n for ens (the width of a single character). For 
example, to indent each section one-half inch, type: 


nr si 0.5i 


After this, sections will be indented by one-half inch per level of 
depth in the section number. 


Section headers without automatically generated numbers can be done 
using: 


.uh "Title" 
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which will do a section heading, but will put no number on the sec- 
tion. 


5.3 Parts of the Basic Paper 


There are some requests which assist in setting up papers. The .tp 
request initializes for a title page. There are no headers or footers on 
a title page, and unlike other pages you can space down and leave 


blank space at the top. For example, a typical title page might 
appear as: 


.tp 

.Sp 21 

ALC 

THE GROWTH OF TOENAILS 
IN UPPER PRIMATES 


.Sp 
Frank N. Furter 
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Typesetting Mathematics — User’s Guide 
(Second Edition) 


Abstract 


This is the user’s guide for a system for typesetting mathematics, 
using the phototypesetters on the UNIX and GCOS operating systems. 


Mathematical expressions are described in a language designed to be 
easy to use by people who know neither mathematics nor typesetting. 
Enough of the language to set in-line expressions like 
lim (tan x)*"** = 1 or display equations like 


x—n/2 


G(z) 


li 


einGle) = ex + 5,2" = Sy zt/k 
me emer ae A 


el 


S}2? So2? S324 
as Cae aaa 1+ ——+ tee 


Il 


N 
7) 
to 
N 
nd 


k k ne 
me0] kkk 20 1 'ky! 22k! mk,,! 
kt 2k, + + mk =m 


can be learned in an hour or so. 


The language interfaces directly with the phototypesetting language 
TROFF, so mathematical expressions can be embedded in the running 
text of a manuscript, and the entire document produced in one pro- 
cess. This user’s guide is an example of its output. 


Source: Brian W. Kernighan and Lorinda L. Cherry. Typesetting Mathematics — 
User's Guide (Second Edition) (Murray Hill, N.J.: Bell Laboratories, 1978). 
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The same language may be used with the UNIX formatter NROFF to 
set mathematical expressions on DASI and GSI terminals and Model 
37 teletypes. 


1. Introduction 


EON is a program for typesetting mathematics on the Graphics Sys- 
tems phototypesetters on the UNIX operating system. The EQN 
language was designed to be easy to use by people who know neither 
mathematics nor typesetting. Thus EQN knows relatively little about 
mathematics. In particular, mathematical symbols like +, —, x, 
parentheses, and so on have no special meanings. EQN is quite happy 
to set garbage (but it will look good). 


EQN works as a preprocessor for the typesetter formatter, TROFF[1], 
so the normal mode of operation is to prepare a document with both 
mathematics and ordinary text interspersed, and let EQN set the 
mathematics while TROFF does the body of the text. 


On UNIX, EQN will also produce mathematics on DASI and GSI ter- 
minals and on Model 37 teletypes. The input is identical, but you 
have to use the programs NEQN and NROFF instead of EQN and 
TROFF. Of course, some things won’t look as good because terminals 
don’t provide the variety of characters, sizes and fonts that a 
typesetter does, but the output is usually adequate for proofreading. 


To use EQN on UNIX, 


eqn files | troff 


2. Displayed Equations 


To tell EQN where a mathematical expression begins and ends, we 
mark it with lines beginning .EQ and .EN. Thus if you type the lines 


.EQ 
X=ytz 
.EN 


your output will look like 
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x=ytz 


The .EQ and .EN are copied through untouched; they are not other- 
wise processed by EQN. This means that you have to take care of 
things like centering, numbering, and so on yourself. The most com- 
mon way is to use the TROFF and NROFF macro package package 
““—ms” developed by M. E. Lesk[{3], which allows you to center, 
indent, left-justify and number equations. 


With the “‘—ms’’ package, equations are centered by default. To 
left-justify an equation, use EQI instead of .EQ. To indent it, use 
-EQI. Any of these can be followed by an arbitrary ‘equation 
number’ which will be placed at the right margin. For example, the 
Input 


.EQ I (3.1a) 
x = f(y/2) + y/2 
.EN 


produces the output 


x=f (y/2)+y/2 (3.1a) 


There is also a shorthand notation so in-line expressions like 7? can 
be entered without .EQ and .EN. We will talk about it in section 19. 


3. Input Spaces 


Spaces and newlines within an expression are thrown away by EQN. 
(Normal text is left absolutely alone.) Thus between .EQ and .EN, 


X=y+z 
and 
x=yt+z 


and 


and so on all produce the same output 
X=yrz 
You should use spaces and newlines freely to make your input 
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equations readable and easy to edit. In particular, very long lines are 
a bad idea, since they are often hard to fix if you make a mistake. 


4. Output Spaces 


To force extra spaces into the ourpur, use a tilde ““~”’ for each space 
you want: 

XT =TyT+7Z 
gives 


x=ytz2 
You can also use a circumflex ‘‘~’’, which gives a space half the width 
of a tilde. It is mainly useful for fine-tuning. Tabs may also be used 
to position pieces of an expression, but the tab stops must be set by 
TROFF commands. 


5. Symbols, Special Names, Greek 


EQN knows some mathematical symbols, some mathematical names, 
and the Greek alphabet. For example, 


x=2 pi int sin ( omega t)dt 
produces 
x=2nfsin(wr)dr 


Here the spaces in the input are necessary to tell EQN that inr, pi, sin 
and omega are separate entities that should get special treatment. 
The sin, digit 2, and parentheses are set in roman type instead of 
italic; pi and omega are made Greek; and int becomes the integral 
sign. 


When in doubt, leave spaces around separate parts of the input. A 
very common error is to type f(pi) without leaving spaces on both 
sides of the pi. As a result, EQN does not recognize pi as a special 
word, and it appears as f (pi) instead of f (7). 


A complete list of EQN names appears in section 23. Knowledgeable 
users can also use TROFF four-character names for anything EQN 
doesn’t know about, like \(bs for the Bell System sign ©. 


12—4 Programmer's Guide: CTIX Supplement 


6. Spaces, Again 


The only way EQN can deduce that some sequence of letters might be 
special is if that sequence is separated from the letters on either side 
of it. This can be done by surrounding a special word by ordinary 
spaces (or tabs or newlines), as we did in the previous section. 


You can also make special words stand out by surrounding them with 
tildes or circumflexes: 


x~=72~ pi~int~ sin7 (~omega~t~)~ dt 
is much the same as the last example, except that the tildes not only 


separate the magic words like sin, omega, and so on, but also add 
extra spaces, one space per tilde: 


x =2nfsin(wt ) dt 


Special words can also be separated by braces { } and double quotes 
"...", which have special meanings that we will see soon. 


7. Subscripts and Superscripts 


Subscripts and superscripts are obtained with the words sub and sup. 
x sup 2 + y subk 
gives 


x+y 


EQN takes care of all the size changes and vertical motions needed to 
make the output look right. The words sub and sup must be sur- 
rounded by spaces; x sub2 will give you xsub2 instead of x,. Further- 
more, don’t forget to leave a space (or a tilde, etc.) to mark the end 
of a subscript or superscript. A common error is to say something 


like 
y = (x sup 2)+1 
which causes 


y =(x2)7! 


instead of the intended 


Typesetting Mathematics — User's Guide (Second Edition) 12—5 


y =(x7)+1 
Subscripted subscripts and superscripted superscripts also work: 
x sub i sub 1 
x: 


ust 


A subscript and superscript on the same thing are printed one above 
the other if the subscript comes first: 


x sub i sup 2 


2 
xj 


Other than this special case, sub and sup group to the right, so 
x sup y sub z means x”", not x?,. 


8. Braces for Grouping 


Normally, the end of a subscript or superscript is marked simply by a 
blank (or tab or tilde, etc.) What if the subscript or superscript is 
something that has to be typed with blanks in it? In that case, you 
can use the braces { and } to mark the beginning and end of the sub- 
script or superscript: 


e sup {i omega t} 


iwt 
e 


Rule: Braces can always be used to force EQN to treat something as a 
unit, or just to make your intent perfectly clear. Thus: 
x sub {i sub 1} sup 2 


is 


with braces, but 


x sub i sub 1 sup 2 
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which is rather different. 
Braces can occur within braces if necessary: 


e sup {i pi sup {rho +1}} 


- pel 
iT 
é€ 


The general rule is that anywhere you could use some single thing like 
x, you can use an arbitrarily complicated thing if you enclose it in 
braces. EQN will look after all the details of positioning it and mak- 
ing it the right size. 


In all cases, make sure you have the right number of braces. Leaving 
one out or adding an extra will cause EQN to complain bitterly. 


Occasionally you will have to print braces. To do this, enclose them 
in double quotes, like "{". Quoting is discussed in more detail in 
section 14. 


9. Fractions 


To make a fraction, use the word over: 
a+b over 2c =1 


gives 


The line is made the right length and positioned automatically. 
Braces can be used to make clear what goes over what: 


{alpha + beta} over {sin (x)} 
at Be 
sin(x ) 


What happens when there is both an over and a sup in the same 
expression? In such an apparently ambiguous case, EQN does the sup 
before the over, so 


—b sup 2 over pi 
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2 


2 & 
instead of —b™ The rules which decide which operation is 


is — 
7 

done first in cases like this are summarized in section 23. When in 

doubt, however, use braces to make clear what goes with what. 


10. Square Roots 


To draw a square root, use sqrt: 
sqrt atb + 1 over sqrt {ax sup 2 +bx+c} 


Vatb + a 
Vax?+bx +c 


CAUTION __ 


Square roots of tall quantities look lousy, because a root-sign 
big enough to cover the quantity is too dark and heavy: 


sqrt {a sup 2 over b sub 2} 


< 
Rae 


Big square roots are generally better written as something to the 
power ‘2: 


(a/b >)* 


which is 


(a sup 2 /b sub 2 ) sup half 
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11. Summation, Integral, Etc. 


Summations, integrals, and similar constructions are easy: 
sum from i=0 to {i= inf} x sup i 


produces 


Notice that we used braces to indicate where the upper part i= 
begins and ends. No braces were necessary for the lower part i=0, 
because it contained no blanks. The braces will never hurt, and if the 
from and to parts contain any blanks, you must use braces around 
them. 


The from and to parts are both optional, but if both are used, they 
have to occur in that order. 


Other useful characters can replace the sum in our example: 
int prod union inter 


become, respectively, 


fe Whe ds Wy 


Since the thing before the from can be anything, even something in 
braces, from-to can often be used in unexpected ways: 


lim from {n — > inf} x sub n =O 


limx, =0 


Ne 


12. Size and Font Changes 


By default, equations are set in 10-point type with standard 
mathematical conventions to determine what characters are in roman 
and what in italic. Although EQN makes a valiant attempt to use 
esthetically pleasing sizes and fonts, it is not perfect. To change sizes 
and fonts, use size n and roman, italic, bold and fat. Like sub and 
sup, size and font changes affect only the thing that follows them, and 
revert to the normal situation at the end of it. Thus 
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bold x y 
is 
xy 


and 


size 14 bold x = y + 
size 14 {alpha + beta} 


gives 
x=y tat+B 


As always, you can use braces if you want to affect something more 
complicated than a single letter. For example, you can change the 
size of an entire equation by 


size 12 { ... } 


Legal sizes which may follow size are 6, 7, 8, 9, 10, 11, 12, 14, 16, 
18, 20, 22, 24, 28, 36. You can also change the size by a given 
amount; for example, you can say size +2 to make the size two points 
bigger, or size —3 to make it three points smaller. This has the 
advantage that you don’t have to know what the current size is. 


If you are using fonts other than roman, italic and bold, you can say 
font X where X is a one character TROFF name or number for the 
font. Since EQN is tuned for roman, italic and bold, other fonts may 
not give quite as good an appearance. 


The fat operation takes the current font and widens it by overstriking: 
fat grad is V and fat {x sub i} is x;. 


If an entire document is to be in a non-standard size or font, it is a 
severe nuisance to have to write out a size and font change for each 
equation. Accordingly, you can set a “global” size or font which 
thereafter affects all equations. At the beginning of any equation, 
you might say, for instance, 


EQ 
gsize 16 
gfont R 
.EN 
to set the size to 16 and the font to roman thereafter. In place of R, 


you can use any of the TROFF font names. The size after gsize can 
be a relative change with + or —. 
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Generally, gsize and gfont will appear at the beginning of a document 
but they can also appear thoughout a document: the global font and 
size can be changed as often as needed. For example, in a footnotet+ 
you will typically want the size of equations to match the size of the 
footnote text, which is two points smaller than the main text. Don’t 
forget to reset the global size at the end of the footnote. 


13. Diacritical Marks 


To get funny marks on top of letters, there are several words: 


x dot x 
x dotdot x 
x hat z 
x tilde od 
xX vec x 
x dyad oa 
x bar x 
x under x 


The diacritical mark is placed at the right height. The bar and under 
are made the right length for the entire construct, as in x+y+z; other 
marks are centered. 


14. Quoted Text 


Any input entirely within quotes ("...".) is not subject to any of the 
font changes and spacing adjustments normally done by the equation 
setter. This provides a way to do your own spacing and adjusting if 
needed: 


italic "sin(x)" + sin (x) 


sin(x) +sin(x ) 


$~ Like this one, in which we have a few random expressions like x; and 7’. The 
sizes for these were set by the command gsize —2. 
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Quotes are also used to get braces and other EON keywords printed: 
"{ size alpha }" 


{ size alpha } 


and 


roman "{ size alpha }" 


{ size alpha } 


The construction "" is often used as a place-holder when grammati- 
cally EQN needs something, but you don’t actually want anything in 
your output. For example, to make 7He, you can’t just type sup 2 
roman He because a sup has to be a superscript on something. Thus 
you must say 


"" sup 2 roman He 


To get a literal quote use “‘\"”’. TROFF characters like \(bs can 
appear unquoted, but more complicated things like horizontal and 
vertical motions with \h and \v should always be quoted. (If you’ve 
never heard of \h and \v, ignore this section.) 


15. Lining Up Equations 


Sometimes it’s necessary to line up a series of equations at some hor- 
izontal position, often at an equals sign. This is done with two opera- 
tions called mark and lineup. 


The word mark may appear once at any place in an equation. It 
remembers the horizontal position where it appeared. Successive 
equations can contain one occurrence of the word lineup. The place 
where lineup appears is made to line up with the place marked by the 
previous mark if at all possible. Thus, for example, you can say 

-EQI 

x+y mark = z 

.EN 

.EQI 

x lineup = 1 

.EN 
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to produce 
xt+y=z 
x=1 
For reasons too complicated to talk about, when you use EQN and 
““_ms’’, use either .EQI or .EQL. Mark and lineup don’t work with 
centered equations. Also bear in mind that mark doesn’t look ahead; 


x mark =1 
x+y lineup =z 


isn’t going to work, because there isn’t room for the x+y part after 
the mark remembers where the x is. 


16. Big Brackets, Etc. 


To get big brackets [], braces { }, parentheses (), and bars 
around things, use the left and right commands: 


left € a over b + 1 right } 
~=~ left (c over d right ) 


+ left [ e right ] 
ela e) 


The resulting brackets are made big enough to cover whatever they 
enclose. Other characters can be used besides these, but the are not 
likely to look very good. One exception is the floor and ceiling char- 
acters: 


is 


left floor x over y right floor 
<= left ceiling a over b right ceiling 


Fe | 


Several warnings about brackets are in order. First, braces are typi- 
cally bigger than brackets and parentheses, because they are made up 
of three, five, seven, etc., pieces, while brackets can be made up of 
two, three, etc. Second, big left and right parentheses often look 
poor, because the character set is poorly designed. 


produces 
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The right part may be omitted: a ‘‘left something” need not have a 
corresponding ‘‘right something’. If the right part is omitted, put 
braces around the thing you want the left bracket to encompass. Oth- 
erwise, the resulting brackets may be too large. 


If you want to omit the /eft part, things are more complicated, 
because technically you can’t have a right without a corresponding 
left. Instead you have to say 


left. 27" 2.4 right ) 


for example. The /eft "" means a “‘left nothing’. This satisfies the 
rules without hurting your output. 


17. Piles 


There is a general facility for making vertical piles of things; it comes 
in several flavors. For example: 


A ~=7 left [ 

pile { a above b above c } 

~~ pile { x above y above z } 
right | 


will make 


ax 

A= |by 

Cc Zz 
The elements of the pile (there can be as many as you want) are cen- 
tered one above another, at the right height for most purposes. The 
keyword above is used to separate the pieces; braces are used around 


the entire list. The elements of a pile can be as complicated as 
needed, even containing more piles. 


Three other forms of pile exist: /pile makes a pile with the elements 
left-justified; rpile makes a right-justified pile; and cpile makes a cen- 
tered pile, just like pile. The vertical spacing between the pieces is 
somewhat larger for /-, r- and cpiles than it is for ordinary piles. 
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roman sign (x)7=~ 


left £ 

Ipile €1 above 0 above -1} 

~~ Ipile 

Cif~x>0 above if~x=0 above if~x<0} 

makes 
1 if x >0 
sign(x) = )0  ifx =0 

~—1 ifx <0 


Notice the left brace without a matching right one. 


18. Matrices 


It is also possible to make matrices. For example, to make a neat 
array like 


you have to type 


matrix { 
ccol { x sub i above y subi } 
ccol { x sup 2 above y sup 2 } 
} 


This produces a matrix with two centered columns. The elements of 
the columns are then listed just as for a pile, each element separated 
by the word above. You can also use /col or rcol to left or right 
adjust columns. Each column can be separately adjusted, and there 
can be as many columns as you like. 


The reason for using a matrix instead of two adjacent piles, by the 
way, is that if the elements of the piles don’t all have the same 
height, they won’t line up properly. A matrix forces them to line up, 
because it looks at the entire structure before deciding what spacing 
to use. 


A word of warning about matrices— each column must have the same 
number of elements in it. The world will end if you get this wrong. 
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19. Shorthand for In-line Equations 


In a mathematical document, it is necessary to follow mathematical 
conventions not just in display equations, but also in the body of the 
text, for example by making variable names like $x$ italic. Although 
this could be done by surrounding the appropriate parts with .EQ and 
.EN, the continual repetition of .EQ and .EN is a nuisance. Further- 
more, with ‘—ms’, .EQ and .EN imply a displayed equation. 


EQN provides a shorthand for short in-line expressions. You can 
define two characters to mark the left and right ends of an in-line 
equation, and then type expressions right in the middle of text lines. 
To set both the left and right characters to dollar signs, for example, 
add to the beginning of your document the three lines 


.EQ 
delim $$ 
._EN 


Having done this, you can then say things like 


Let $alpha sub i$ be the primary variable, and let $beta$ be zero. 
Then we can show that $x sub 1$ is $>=0$. 


This works as you might expect—spaces, newlines, and so on are sig- 
nificant in the text, but not in the equation part itself. Multiple equa- 
tions can occur in a single input line. 


Enough room is left before and after a line that contains in-line 
expressions that something like 3x; does not interfere with the lines 
surrounding it. im 

To turn off the delimiters, 


.EQ 
delim off 
.EN 


CAUTION 


Don’t use braces, tildes, circumflexes, or double quotes as 
delimiters— chaos will result. 
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20. Definitions 


EQN provides a facility so you can give a frequently-used string of 
characters a name, and thereafter just type the name instead of the 
whole string. For example, if the sequence 


x sub i sub 1 + y subi sub | 


appears repeatedly throughout a paper, you can save re-typing it each 
time by defining it like this: 

define xy ’x subi sub 1 + y suoi sub 1’ 
This makes xy a shorthand for whatever characters occur between the 
single quotes in the definition. You can use any character instead of 


quote to mark the ends of the definition, so long as it doesn’t appear 
inside the definition. 


Now you can use xy like this: 
-EQ 
f(x) = xy... 
.EN 


and so on. Each occurrence of xy will expand into what it was 
defined as. Be careful to leave spaces or their equivalent around the 
name when you actually use it, so EQN will be able to identify it as 
special. 


There are several things to watch out for. First, although definitions 
can use previous definitions, as in 


.EQ 

define xi ’ x subi’ 
define xil * xisub1’ 
.EN 


don’t define something in terms of itself. A favorite error is to say 
define X * roman X’ 


This is a guaranteed disaster, since X is now defined in terms of 
itself. If you say 


define X * roman "X" °” 
however, the quotes protect the second X, and everything works fine. 


EQN keywords can be redefined. You can make / mean over by say- 
ing 
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define / ” over’ 
or redefine over as / with 


define over */’ 


If you need different things to print on a terminal and on the 
typesetter, it is sometimes worth defining a symbol differently in 
NEON and EQN. This can be done with ndefine and tdefine. A defin- 
ition made with ndefine only takes effect if you are running NEQN; if 
you use tdefine, the definition only applies for EQN. Names defined 
with plain define apply to both EQN and NEON. 


21. Local Motions 


Although EQN tries to get most things at the right place on the paper, 
it isn’t perfect, and occasionally you will need to tune the output to 
make it just right. Small extra horizontal spaces can be obtained with 
tilde and circumflex. You can also say back n and fwd n to move 
small amounts horizontally. n is how far to move in 1/100’s of an em 
(an em is about the width of the letter ‘m’.) Thus back 50 moves 
back about half the width of an m. Similarly you can move things up 
or down with up n and down n. As with sub or sup, the local motions 
affect the next thing in the input, and this can be something arbi- 
trarily complicated if it is enclosed in braces. 


22. A Large Example 


Here is the complete source for the three display equations in the 
abstract of this guide. 


.EQI 

G(z)~ mark =~ e sup { In ~ G(z) } 

~=~ exp left ( 

sum from k>=1 {S sub k z sup k} over k right ) 
“=~ prod from k>=1 e sup {S sub k z sup k /k} 
.EN 

.EQI 

lineup = left (1+ Ssub1z+ 

{ S sub 1 sup 2 z sup 2 } over 2! + ... right ) 


12—18 Programmer's Guide: CTIX Supplement 


left (1+ { S sub 2 z sup 2 } over 2 

+ { Ssub 2 sup 2 z sup 4 } over { 2 sup 2 cdot 2! } 

+... right)... 

.EN 

.EQI 

lineup = sum from m>=0 left ( 

sum from 

pile { k sub1 ,k sub2,..., k subm >=0 

above 

k sub 1 +2k sub 2 + ... +mk sub m =m} 

{ S sub 1 sup {k sub 1} } ov.” {1 sup k sub 1 k sub 1 ! } ~ 
{ S sub 2 sup {k sub 2} } over {2 sup k sub 2 k sub2! } ~ 


£S sub m sup {k sub m} } over {m sup k sub m k sub m ! } 
right ) z sup m 
.EN 


23. Keywords, Precedences, Etc. 


If you don’t use braces, EQN will do operations in the order shown in 
this list. 


dyad vec under bar tilde hat dot dotdot 
fwd back down up 

fat roman italic bold size 

sub sup sqrt over 

from to 


These operations group to the left: 
over sqrt left right 
All others group to the right. 


Digits, parentheses, brackets, punctuation marks, and _ these 
mathematical words are converted to Roman font when encountered: 


sin cos tan sinh cosh tanh arc 
max min lim log In exp 
Re Im and if for det 
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These character sequences are recognized and translated as shown. 


>= = approx = 

<= < nothing 

—— = cdot 

I= # times x 

+ + del V 

—> - grad V 

< ae 

<< « Pe roe 

>> >> sum >> 

inf oo or f 

partial a 

half % prog I] 

prime ; union U 
inter a) 


To obtain Greek letters, simply spell them out in whatever case you 
want: 


iota 


DELTA A L 

GAMMA T kappa K 
LAMBDA A lambda 
OMEGA fe) mu be 
PHI P nu v 
PI N omega w 
PSI Vv omicron o 
SIGMA x phi ob 
THETA rc) pi TT 
UPSILON Y psi us 
XI = rho p 
alpha a sigma a 
beta B tau T 

chi x theta 6 
delta 8 upsilon =v 
epsilon € xi é 

eta n zeta 4 

gamma y 
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These are all the words known to EQN (except for characters with 
names), together with the section where they are discussed. 


above 17, 18 Ipile 17 
back 21 mark 15 
bar 13 matrix 18 
bold 12 ndefine 20 
ccol 18 over 9 
col 18 pile 17 
cpile 17 rcol 18 
define 20 right 16 
delim 19 roman 12 
dot 13 rpile 17 
dotdot 13 size 12 
down 21 sqrt 10 
dyad 13 sub 7 
fat 12 sup 7 
font 12 tdefine 20 
from 11 tilde 13 
fwd 21 to 11 
gfont 12 under 13 
gsize 12 up 21 
hat 13 vec 13 
italic 12 aien 4,6 
Ical 18 {} 8 
left 16 Lars 8, 14 
lineup 15 


24. Troubleshooting 


If you make a mistake in an equation, like leaving out a brace (very 
common) or having one too many (very common) or having a sup 
with nothing before it (common), EQN will tell you with the message 


syntax error between lines x and y, file z 


where x and y are approximately the lines between which the trouble 
occurred, and z is the name of the file in question. The line numbers 
are approximate—look nearby as well. There are also self- 
explanatory messages that arise if you leave out a quote or try to run 
EQN on a non-existent file. 
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If you want to check a document before actually printing it (on UNIX 
only), 


eqn files >/dev/null 
will throw away the output but print the messages. 


If you use something like dollar signs as delimiters, it is easy to leave 
one out. This causes very strange troubles. The program checkeq 
checks for misplaced or missing dollar signs and similar troubles. 


In-line equations can only be so big because of an internal buffer in 
TROFF. If you get a message ‘“‘word overflow”, you have exceeded 
this limit. If you print the equation as a displayed equation this mes- 
sage will usually go away. The message “‘line overflow” indicates you 
have exceeded an even bigger buffer. The only cure for this is to 
break the equation into two separate ones. 


On a related topic, EQN does not break equations by itself—you must 
split long equations up across multiple lines by yourself, marking each 
by a separate .EQ ... .EN sequence. EQN does warn about equations 
that are too long to fit on one line. 


25. Use on UNIX 


To print a document that contains mathematics on the UNIX 
typesetter, 


eqn files | troff 


If there are any TROFF options, they go after the TROFF part of the 
command. For example, 


eqn files | troff -ms 
A compatible version of EQN can be used on devices like teletypes 


and DASI and GSI terminals which have half-line forward and reverse 


capabilities. To print equations on a Model 37 teletype, for example, 
use 


neqn files | nroff 


The language for equations recognized by NEQN is identical to that of 
EON, although of course the output is more restricted. 
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To use a GSI or DASI terminal as the output device, 
neqn files | nroff -Tx 
where x is the terminal type you are using, such as 300 or 3008S. 


EQN and NEQN can be used with the TBL program[2] for setting 
tables that contain mathematics. Use TBL before [NJEQN, like this: 


tbl files | eqn | troff 
tbl files | neqn | nroff 
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Tbl — A Program to Format Tables 


Abstract 


Tbl is a document formatting preprocessor for troff or nroff which 
makes even fairly complex tables easy to specify and enter. It is 
available on the PDP-11 UNIX system and on Honeywell 6000 GCos. 
Tables are made up of columns which may be independently cen- 
tered, right-adjusted, left-adjusted, or aligned by decimal points. 
Headings may be placed over single columns or groups of columns. 
A table entry may contain equations, or may consist of several rows 
of text. Horizontal or vertical lines may be drawn as desired in the 
table, and any table or element may be enclosed in a box. For exam- 
ple: 


1970 Federal Budget Transfers 
{_ (in billions of dollars) | 
Stite Taxes Money Net 
le collected spent 
New York 22.91 21.35 -1.56 
New Jersey 8.33 6.96 -1.37 
Connecticut 4.12 3.10 —1.02 
Maine 0.74 0.67 —0.07 
California 22.29 22.42 +0.13 
New Mexico 0.70 1.49 +0.79 
Georgia 3.30 4.28 +0.98 
Mississippi 1.15 2.32 41.17 
Texas I 9.33 11.13 +1.80 


Source: M. E. Lesk, Tbl — A Program to Format Tables (Murray Hill, N.J.: Bell 
Laboratories, 1979). 


Tbl — A Program to Format Tables 13—I 


Introduction 


Tb! turns a simple description of a table into a troff or nroff [1] pro- 
gram (list of commands) that prints the table. 7b/ may be used on 
the PDP-11 UNIX [2] system and on the Honeywell 6000 GCOS system. 
It attempts to isolate a portion of a job that it can successfully handle 
and leave the remainder for other programs. Thus rb/ may be used 
with the equation formatting program eqn [3] or various layout macro 
packages [4,5,6], but does not duplicate their functions. 


This memorandum is divided into two parts. First we give the rules 
for preparing rb/ input; then some examples are shown. The descrip- 
tion of rules is precise but technical, and the beginning user may 
prefer to read the examples first, as they show some common table 
arrangements. A section explaining how to invoke tbl precedes the 
examples. To avoid repetition, henceforth read troff as “troff or 


nroff.” 


The input to rb/ is text for a document, with tables preceded by a 
“TS” (table start) command and followed by a ‘‘.TE” (table end) 
command. Tbl processes the tables, generating troff formatting com- 
mands, and leaves the remainder of the text unchanged. The ‘‘.TS” 
and ‘“‘.TE” lines are copied, too, so that troff page layout macros 
(such as the memo formatting macros [4] ) can use these lines to del- 
imit and place tables as they see fit. In particular, any arguments on 
the “*.TS” or ‘*.TE” lines are copied but otherwise ignored, and may 
be used by document layout macro commands. 


The format of the input is as follows: 


text 
.TS 
table 
.TE 
text 
-TS 
table 
TE 
text 


where the format of each table is as follows: 
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.TS 
Options 3 
formar . 


data 
.TE 


Each table is independent, and must contain formatting information 
followed by the data to be entered in the table. The formatting infor- 
mation, which describes the individual columns and rows of the table, 
may be preceded by a few options that affect the entire table. A 
detailed description of tables is given in the next section. 


Input Commands 


As indicated above, a table contains, first, global options, then a for- 
mat section describing the layout of the table entries, and then the 
data to be printed. The format and data are always required, but not 
the options. ‘The various parts of the table are entered as follows: 


1) OPTIONS. There may be a single line of options affecting the 
whole table. If present, this line must follow the .TS line 
immediately and must contain a list of option names separated 
by spaces, tabs, or commas, and must be terminated by a semi- 
colon. The allowable options are: 


center center the table (default is left-adjust); 

expand make the table as wide as the current line length; 
box enclose the table in a box; 

allbox enclose each ttem in the table in a box; 


doublebox enclose the table in two boxes; 

tab (x) use x instead of tab to separate data items. 
linesize (7) set lines or rules (e.g. from box) in n point type; 
delim (xy) recognize x and y as the eqn delimiters. 


The tbl program tries to keep boxed tables on one page by issu- 
ing appropriate “need” (.ne) commands. These requests are 
calculated from the number of lines in the tables, and if there 
are spacing commands embedded in the input, these requests 
may be inaccurate; use normal troff procedures, such as keep- 
release macros, in that case. The user who must have a multi- 
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page boxed table should use macros designed for this purpose, 
as explained below under “Usage.” 


2) FORMAT. The format section of the table specifies the layout 
of the columns. Each line in this section corresponds to one 
line of the table (except that the last line corresponds to all fol- 
lowing lines up to the next .T&, if any — see below), and each 
line contains a key-letter for each column of the table. It is 
good practice to separate the key letters for each column by 
spaces or tabs. Each key-letter is one of the following: 


Lorl _ to indicate a left-adjusted column entry; 
Rorr_ to indicate a right-adjusted column entry; 
Core to indicate a centered column entry; 


Norn_ to indicate a numerical column entry, to be aligned 
with other numerical entries so that the units digits 
of numbers line up; 


A ora __ to indicate an alphabetic subcolumn; all correspond- 
ing entries are aligned on the left, and positioned so 
that the widest is centered within the column (see 
example on page 21); 


Sors to indicate a spanned heading, i.e. to indicate that 
the entry from the previous column continues across 
this column (not allowed for the first column, obvi- 
ously); or 


“ to indicate a vertically spanned heading, i.e. to indi- 
cate that the entry from the previous row continues 
down through this row. (Not allowed for the first 
row of the table, obviously). 


When numerical alignment is specified, a location for the 
decimal point is sought. The rightmost dot (.) adjacent to a 
digit is used as a decimal point; if there is no dot adjoining a 
digit, the rightmost digit is used as a units digit; if no alignment 
is indicated, the item is centered in the column. However, the 
special non-printing character string \& may be used to over- 
ride unconditionally dots and digits, or to align alphabetic data; 
this string lines up where a dot normally would, and then disap- 
pears from the final output. In the example below, the items 
shown at the left will be aligned (in a numerical column) as 
shown on the right: 
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13 13 


4.2 4.2 
26 .4.12 26.4.12 
abc abc 
abc\ & abc 
43\ &3 .22 433 .22 
749 .12 749.12 


NOTE 


If numerical data are used in the same column with 
wider L or r type table entries, the widest number is cen- 
tered relative to the wider L or r items (L is used instead 
of | for readability; they have the same meaning as key- 
letters). Alignment within the numerical items is 
preserved. This is similar to the behavior of a type data, 
as explained above. However, alphabetic subcolumns 
(requested by the a key-letter) are always slightly 
indented relative to L items; if necessary, the column 
width is increased to force this. This is not true for n 
type entries. 


CAUTION 


The n and a items should not be used in the same 
column. 


For readability, the key-letters describing each column should 
be separated by spaces. The end of the format section is indi- 
cated by a period. The layout of the key-letters in the format 
section resembles the layout of the actual data in the table. 
Thus a simple format might appear as: 

cs s 

Inn. 
which specifies a table of three columns. The first line of the 
table contains a heading centered across all three columns; each 
remaining line contains a left-adjusted item in the first column 
followed by two columns of numerical data. A sample table in 
this format might be: 
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Overall title 


Item-a 34.22 9.1 
Item-b 12.65 .02 
Items: c,d,e 23 5.8 
Total 69.87 14.92 


There are some additional features of the key-letter system: 


’ 


Horizontal lines — A _ key-letter may be replaced by ‘_ 
(underscore) to indicate a horizontal line in place of the 
corresponding column entry, or by ‘=’ to indicate a dou- 
ble horizontal line. If an adjacent column contains a hor- 
izontal line, or if there are vertical lines adjoining this 
column, this horizontal line is extended to meet the 
nearby lines. If any data entry is provided for this 
column, it is ignored and a warning message is printed. 


Vertical lines — A vertical bar may be placed between 
column key-letters. This will cause a vertical line between 
the corresponding columns of the table. A vertical bar to 
the left of the first key-letter or to the right of the last one 
produces a line at the edge of the table. If two vertical 
bars appear between key-letters, a double vertical line is 
drawn. 


Space between columns —- A number may follow the key- 
letter. This indicates the amount of separation between 
this column and the next column. The number normally 
specifies the separation in ens (one en is about the width 
of the letter ‘n’).* If the ‘‘expand’’ option is used, then 
these numbers are multiplied by a constant such that the 
table is as wide as the current line length. The default 
column separation number is 3. If the separation is 
changed the worst case (largest space requested) governs. 


Vertical spanning — Normally, vertically spanned items 
extending over several rows of the table are centered in 
their vertical range. If a key-letter is followed by t or T, 
any corresponding vertically spanned item will begin at 
the top line of its range. 


* More precisely, an en is a number of points (1 point = 1/72 inch) equal to half 


the current type size. 


13—6 Programmer's Guide: CTIX Supplement 


Font changes — A key-letter may be followed by a string 
containing a font name or number preceded by the letter f 
or F. This indicates that the corresponding column 
should be in a different font from the default font (usually 
Roman). All font names are one or two letters; a one- 
letter font name should be separated from whatever fol- 
lows by a space or tab. The single letters B, b, I, and i 
are shorter synonyms for fB and fI. Font change com- 
mands given with the table entries override these specifi- 
cations. 


Point size changes — A key-letter may be followed by the 
letter p or P and a number to indicate the point size of 
the corresponding table entries. The number may be a 
signed digit, in which case it is taken as an increment or 
decrement from the current point size. If both a point 
size and a column separation value are given, one or more 
blanks must separate them. 


Vertical spacing changes — A key-letter may be followed by 
the letter v or V and a number to indicate the vertical line 
spacing to be used within a multi-line corresponding table 
entry. The number may be a signed digit, in which case 
it is taken as an increment or decrement from the current 
vertical spacing. A column separation value must be 
separated by blanks or some other specification from a 
vertical spacing request. This request has no effect unless 
the corresponding table entry is a text block (see below). 


Column width indication — A key-letter may be followed by 
the letter w or W and a width value in parentheses. This 
width is used as a minimum column width. If the largest 
element in the column is not as wide as the width value 
given after the w, the largest element is assumed to be 
that wide. If the largest element in the column is wider 
than the specified value, its width is used. The width is 
also used as a default line length for included text blocks. 
Normal troff units can be used to scale the width value; if 
none are used, the default is ens. If the width specifica- 
tion is a unitless integer the parentheses may be omitted. 
If the width value is changed in a column, the /ast one 
given controls. 


Equal width columns — A key-letter may be followed by the 
letter e or E to indicate equal width columns. All 
columns whose key-letters are followed by e or E are 
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made the same width. This permits the user to get a 
group of regularly spaced columns. 


NOTE 


The order of the above features is immaterial; they 
need not be separated by spaces, except as indi- 
cated above to avoid ambiguities involving point 
size and font changes. Thus a numerical column 
entry in italic font and 12 point type with a 
minimum width of 2.5 inches and separated by 6 
ens from the next column could be specified as 


npl2w(2.5i)fI 6 


Alternative notation — Instead of listing the format of succes- 
sive lines of a table on consecutive lines of the format sec- 
tion, successive line formats may be given on the same 
line, separated by commas, so that the format for the 
example above might have been written: 


ess,Inn. 


Default — Column descriptors missing from the end of a for- 
mat line are assumed to be L. The longest line in the for- 
mat section, however, defines the number of columns in 
the table; extra columns in the data are ignored silently. 


3) DATA. The data for the table are typed after the format. 
Normally, each table line is typed as one line of data. Very 
long input lines can be broken: any line whose last character is 
\ is combined with the following line (and the \ vanishes). 
The data for different columns (the table entries) are separated 
by tabs, or by whatever character has been specified in the 
option tabls option. There are a few special cases: 


Troff commands within tables — An input line beginning with 
a ‘.’ followed by anything but a number is assumed to be 
a command to troff and is passed through unchanged, 
retaining its position in the table. So, for example, space 
within a table may be produced by “‘.sp’’ commands in 
the data. 
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Full width horizontal lines — An input line containing only 
the character _ (underscore) or = (equal sign) is taken to 
be a single or double line, respectively, extending the full 
width of the table. 


Single column horizontal lines — An input table entry con- 
taining only the character _ or = is taken to be a single or 
double line extending the full width of the column Such 
lines are extended to meet horizontal or vertical lines 
adjoining this column. To obtain these characters expli- 
citly in a column, either precede them by \& or follow 
them by a space before the usual tab or newline. 


Short horizontal lines — An input table entry containing only 
the string \_ is taken to be a single line as wide as the 
contents of the column. It is not extended to meet 
adjoining lines. 


Vertically spanned items — An input table entry containing 
only the character string \~ indicates that the table entry 
immediately above spans downward over this row. It is 
equivalent to a table format key-letter of ‘~’. 


Text blocks — In order to include a block of text as a table 
entry, precede it by T{ and follow it by T}. Thus the 
sequence 


cee TE 
block of 
text 


is the way to enter, as a single entry in the table, some- 
thing that cannot conveniently be typed as a simple string 
between tabs. Note that the T} end delimiter must begin 
a line; additional columns of data may follow after a tab 
on the same line. See the example on page 17 for an 
illustration of included text blocks in a table. If more 
than twenty or thirty text blocks are used in a table, vari- 
ous limits in the troff program are likely to be exceeded, 
producing diagnostics such as ‘“‘too many string/macro 
names” or ‘‘too many number registers.” 


Text blocks are pulled out from the table, processed 
separately by troff, and replaced in the table as a solid 
block. If no line length is specified in the block of text 
itself, or in the table format, the default is to use 
LxC/(N+1) where L is the current line length, C is the 
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number of table columns spanned by the text, and N is the 
total number of columns in the table. The other parame- 
ters (point size, font, etc.) used in setting the block of text 
are those in effect at the beginning of the table (including 
the effect of the ‘“‘.TS’ macro) and any table format 
specifications of size, spacing and font, using the p, v and 
f modifiers to the column key-letters. Commands within 
the text block itself are also recognized, of course. How- 
ever, troff commands within the table data but not within 


CAUTION 


Although any number of lines may be present in a 
table, only the first 200 lines are used in calculating 
the widths of the various columns. A multi-page 
table, of course, may be arranged as_ several 
single-page tables if this proves to be a problem. 
Other difficulties with formatting may arise 
because, in the calculation of column widths all 
table entries are assumed to be in the font and size 
being used when the ‘‘.TS” command was encoun- 
tered, except for font and size changes indicated 
(a) in the table format section and (b) within the 
table data (as in the entry \s+3\fIdata\fP\s0 ). 
Therefore, although arbitrary troff requests may be 
sprinkled in a table, care must be taken to avoid 
confusing the width calculations; use requests such 
as ‘.ps’ with care. 


4) | ADDITIONAL COMMAND LINES. If the format of a table must 
be changed after many similar lines, as with sub-headings or 
summarizations, the ‘‘.T&”’ (table continue) command can be 
used to change column parameters. The outline of such a table 
input is: 
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.TS 
options 3 
format . 
data 
.T& 
format . 
data 
.T& 
format . 


data 
.TE 


as in the examples on pages 14 and 21. Using this procedure, 
each table line can be close to its corresponding format line. 


CAUTION 


It is not possible to change the number of columns, the 
space between columns, the global options such as box, 


or the selection of columns to be made equal width. 


Usage 


On UNIX, tb/ can be run on a simple table with the command 
tbl input-file | troff 


but for more complicated use, where there are several input files, and 
they contain equations and ms memorandum layout commands as 
well as tables, the normal command would be 


tbl file-1 file-2 .. . | eqn | troff —ms 


and, of course, the usual options may be used on the troff and eqn 
commands. The usage for nroff is similar to that for troff, but only 
TELETYPE® Model 37 and Diablo-mechanism (DASI or GSI) termi- 
nals can print boxed tables directly. 


For the convenience of users employing line printers without adequate 
driving tables or post-filters, there is a special -TX command line 
option to tbl which produces output that does not have fractional line 
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motions in it. The only other command line options recognized by tbl 
are —ms and —mm which are turned into commands to fetch the 
corresponding macro files; usually it is more convenient to place these 
arguments on the troff part of the command line, but they are 
accepted by rb/ as well. 


Note that when egn and tb/ are used together on the same file rb/ 
should be used first. If there are no equations within tables, either 
order works, but it is usually faster to run 1b/ first, since eqn normally 
produces a larger expansion of the input than rb/. However, if there 
are equations within tables (using the delim mechanism in eqn), tbi 
must be first or the output will be scrambled. Users must also beware 
of using equations in n-style columns; this is nearly always wrong, 
since tb/ attempts to split numerical format items into two parts and 
this is not possible with equations. The user can defend against this 
by giving the delim(xx) table option; this prevents splitting of numeri- 
cal columns within the delimiters. For example, if the egn delimiters 
are $$, giving delim($$) a numerical column such as ‘‘1245 $+- 16$” 
will be divided after 1245, not after 16. 


Tb! limits tables to twenty columns; however, use of more than 16 
numerical columns may fail because of limits in troff, producing the 
“too many number registers’’ message. Troff number registers used 
by tbl must be avoided by the user within tables; these include two- 
digit names from 31 to 99, and names of the forms #x, x+, x |, -x, 
and x—, where x is any lower case letter. The names ##, #—, and 
#* are also used in certain circumstances. To conserve number regis- 
ter names, the n and a formats share a register; hence the restriction 
above that they may not be used in the same column. 


For aid in writing layout macros, rb! defines a number register TW 
which is the table width; it is defined by the time that the “*.TE” 
macro is invoked and may be used in the expansion of that macro. 
More importantly, to assist in laying out multi-page boxed tables the 
macro T# is defined to produce the bottom lines and side lines of a 
boxed table, and then invoked at its end. By use of this macro in the 
page footer a multi-page table can be boxed. In particular, the ms 
macros can be used to print a multi-page boxed table with a repeated 
heading by giving the argument H to the ‘‘.TS” macro. If the table 
start macro is written 


.TSH 
a line of the form 


.TH 


must be given in the table after any table heading (or at the start if 
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none). Material up to the **.TH” is placed at the top of each page of 
table; the remaining lines in the table are placed on several pages as 
required. Note that this is not a feature of tb/, but of the ms layout 


macros. 


Examples 


Here are some examples illustrating features of rb/. The symbol @ in 


the input represents a tab character. 


Output: 
Language Authors Runs on 
Fortran Many Almost anything 
PL/1 IBM 360/370 
C BTL 11/45, H6000,370 
BLISS Carnegie-Mellon PDP-10,11 
IDS Honeywell H6000 
Pascal Stanford 370 

Input 

-TS 

box; 

ece 


Language © Authors © Runs on 


Fortran © Many © Almost anything 
PL/1 © IBM ©360/370 
C@BTL©@11/45,H6000,370 

BLISS © Carnegie-Mellon © PDP-10,11 
IDS © Honeywell © H6000 

Pascal © Stanford ©370 

.TE 
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Input: 


.TS 

allbox; 

css 

ccc 

nnn. 

AT&T Common Stock 
Year ® Price ® Dividend 
1971 © 41-54 ©$2.60 
2@41-54@2.70 

3 @46-55 ©2.87 
4@40-53 ©3.24 

5 ©45-52 ©3 .40 
6@51-59 @ .95* 

.TE 

* (first quarter only) 


Input: 


-TS 

box; 

cf{Bsss. 
Composition of Foods 


TR 

ec |lcss 

e less 

oF ‘ieer fer hes 


Food@® Percent by Weight 
\r OL 

\* © Protein © Fat © Carbo- 
\7 O\7 O\* Chydrate 
-T& 

P{n fin dn. 
Apples® .4© .5@13.0 
Halibut@18.4@5.2@... 


Lima beans@7.5@ .8@22.0 


Milk©®3.3©4.005.0 


Mushrooms @3.5@ .4@6.0 
Rye bread@®9.0@ .6@52.7 


-TE 


Milk 


Halibut 
Lima beans 


Mushrooms 
Rye bread 


|_Dividend 


41-54 


$2.60 


2.70 


46-55 2.87 
40-53 3.24 
45-52 3.40 
$1-59 .95* 


* (first quarter only) 
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Output: 


Major New York Bridges | 
Bridge Designer iu Length 
Brooklyn J. A. Roebling 1595 
Manhattan G. Lindenthal 1470 
Williamsburg L. L. Buck 1600 
Queensborough Palmer & 1182 
Hornbostel 
1380 
Triborough O. H. Ammann Aepreree 
| |_ 383 
Bronx Whitestone O. H. Ammann 2300 
Throgs Neck O. H. Ammann 1800 
George Washington | O. H. Ammann 3500 
Input: 
.TS 
box; 
css 
clcle 
Ti 1ton. 


Major New York Bridges 
Bridge © Designer © Length 


Brooklyn @®J. A. Roebling ©1595 
Manhattan ®@G. Lindenthal ©1470 
Williamsburg @L. L. Buck ©1600 


Queensborough @® Palmer & ©1182 
@© Hornbostel 


© ©1380 
Triborough ®©O. H. Ammann @_ 
® ©383 


Bronx Whitestone ®O. H. Ammann @2300 
Throgs Neck ®O. H. Ammann ©1800 


George Washington ®O. H. Ammann ©3500 
.TE 
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Input: Output: 


TS Stack 
ce 
np-2|[n]. 
D Stack 


iy) 


ff WN 


1 D46 


1) 


an 


Input: Output: 


TS 

box; 
LLL 
LL_ 
LL {| LB 
| Coeeen 
LLL. 
january © february ® march 
april ©may 

june @ july © Months 

august © september 

october © november © december 
TE 


january february march 
april may 
june july 
august september 
october _ november 


december 
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Output: 


New York Area Rocks 


Era Formation Age (years) 
Precambrian Reading Prong \ >1 billion 
Paleozoic Manhattan Prong 400 million 

re 
Mesozoic Newark Basin, 200 million 
incl. Stockton, 
Lockatong, and 
Brunswick for- 
mations; also 
Watchungs and 
Palisades. i 
Cenozoic Coastal Plain On Long Island 


30,000 years; 
Cretaceous sedi- 
ments redepo- 
sited by recent 


glaciation. 


Input: 


-TS 

allbox; 

cfI s_ s 

ce ew(li) cw(li) 
Ip10 Ip10 Ip10. 

New York Area Rocks 


Era © Formation © Age (years) 
Precambrian © Reading Prong ®>1 billion 
Paleozoic © Manhattan Prong ©400 million 


Mesozoic © TL 
na 
Newark Basin, incl. 


Stockton, Lockatong, and Brunswick 
formations; also Watchungs 


and Palisades. 
T} ©200 million 


Cenozoic © Coastal Plain @ T{ 
On Long Island 30,000 years; 
Cretaceous sediments redeposited 


by recent glaciation. 
wad 

T} 

-TE 
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Input: 
EQ 


deli $$ 


.EN 


TS 


doublebox; 


cc 
11. 


Name @ Definition 


.Sp 


.vs +2p 


Gamma @©$GAMMA (z) = int sub 0 sup inf t sup {z-1} e sup -t dt$ 


Output: 


dt 


Name Definition 
Gamma _ [(z)= ae letdt 
Sine fats tet se) 
2i 
2 z 
Error erf(z)= cree ee” 
Bessel Jo(z)= 1 f*cos(z sin®)d @ 
nO 
Zeta &(s)= Sk * (Res>l) 
= 


Sine @$sin (x) = 1 over 2i ( € sup ix - e sup -ix )$ 


Error @$ roman erf (z) = 2 over sqrt pi int sub 0 sup z e sup {-t sup 2} d 
Bessel ©$ J sub 0 (z) = 1 over pi int sub 0 sup pi cos ( z sin theta ) d theta 


Zeta ©$ zeta (s) = sum from k=1 to inf k sup -s ~~( Re7s > 1)$ 


vs -2p 


JRE 


Output: 


This is a paragraph of normal text placed here only to indicate where 
the left and right margins are. In this way the reader can judge the 
appearance of centered tables or expanded tables, and observe how 
such tables are formatted. 


Name 


James J. Florio 
William J. Hughes 
James J. Howard 


Andrew Maguire 
Robert A. Roe 
Henry Helstoski 
Peter W. Rodino, Jr. 
| Joseph G. Minish 

‘ Helen S. Meyner 

| Dominick V. Daniels 
| Edward J. Patten 

| 


: Millicent Fenwick 
; Edwin B. Forsythe 
Matthew J. Rinaldo 


Frank Thompson, Jr. 


(Democrats) 
Office address 


23 S. White Horse Pike, Somerdale 08083 
2920 Atlantic Ave., Adantic City 08401 
801 Bangs Ave., Asbury Park 07712 

10 Rutgers Pl., Trenton 08618 

115 W. Passaic St., Rochelle Park 07662 
U.S.P.O., 194 Ward St., Paterson 07510 
666 Paterson Ave., East Rutherford 07073 
Suite 1435A, 970 Broad St., Newark 07102 
308 Main St., Orange 07050 

32 Bridge St.. Lambertville 08530 

895 Bergen Ave., Jersey City 07306 

Natl. Bank Bldg.. Perth Amboy 08861 


(Republicans) 


41 -N. Bridge St., Somerville 08876 
301 Mill St.. Moorestown 08057 
1961 Mors Ave., Union 07083 


Phone 


609-627-8222 
609-345-4844 
201-774-1600 
609-599-1619 
201-843-0240 
201-523-5152 
201-939-9090 
201-645-3213 
201-645-6363 
609-397-1830 
201-659-7700 
201-826-4610 


201-722-8200 
609-235-6622 


__201-687-4235 | 
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Input: 


-ps 8 

-vs 10p 

.TS 

center box; 

css 

ciss 

cece 

IBIn. 

New Jersey Representatives 

(Democrats) 

“sp .5 

Name © Office address @ Phone 

“sp .5 

James J. Florio®23 S. White Horse Pike, Somerdale 08083 © 609-627-8222 
William J. Hughes@2920 Atlantic Ave., Atlantic City 08401 © 609-345-4844 
James J. Howard @801 Bangs Ave., Asbury Park 07712 © 201-774-1600 
Frank Thompson, Jr. ©10 Rutgers Pl., Trenton 08618 @ 609-599-1619 
Andrew Maguire ©®115 W. Passaic St., Rochelle Park 07662 © 201-843-0240 
Robert A. Roe@U.S.P.O., 194 Ward St., Paterson 07510 © 201-523-5152 
Henry Helstoski©666 Paterson Ave., East Rutherford 07073 © 201-939-9090 
Peter W. Rodino, Jr. @Suite 1435A, 970 Broad St., Newark 07102 © 201-645-3213 
Joseph G. Minish ®308 Main St., Orange 07050 © 201-645-6363 

Helen S. Meyner ® 32 Bridge St., Lambertville 08530 © 609-397-1830 
Dominick V. Daniels ®895 Bergen Ave., Jersey City 07306 © 201-659-7700 
Edward J. Patten@ Natl. Bank Bldg., Perth Amboy 08861 © 201-826-4610 
ssp .5 

T& 

ciss 

IBIn. 

(Republicans) 

“sp .5v 

Millicent Fenwick 41 N. Bridge St., Somerville 08876 D 201-722-8200 
Edwin B. Forsythe ©301 Mill St., Moorestown 08057 @ 609-235-6622 
Matthew J. Rinaldo @® 1961 Morris Ave., Union 07083 © 201-687-4235 

TE 

-ps 10 

vs 12p 
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Output: 


Readability of Text 


Type 


Line Width and Leading for 10-Point 


] 


9 Pica : f . 7 
14 Pica |) -4.5 0.6 0.3 -1.7 
19 Pica || —5.0 —5.1 0.0 -2.0 
31 Pica || -3.7 -3.8 2.4 -3.6 
43 Pica || -9.1 -9.0 5.9 -8.8 

Input: 

.TS 

box, tab(:); 

cbssss 

cp-2ssss 

cllelelele 

ellelelecle 

m2 || n2/n2{/ n2[n. 


Readability of Text 

Line Width and Leading for 10-Point Type 
Line: Sct: 1-Point : 2-Point : 4-Point 

Width : Solid : Leading : Leading : Leading 


9 Picat¥-9.32\26.0°\-5.3:49.1 


14 Pica: \-4.5:\-0.6:\-0.3:\-1.7 
19 Pica: \-5.0:\-5.1: 0.0:\-2.0 
31 Pica: \-3.7:\-3.8:\-2.4:\-3.6 
43 Pica: \-9.1:\-9.0:\-5.9:\-8.8 
.TE 
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Output: 


Some London Transport Statistics 


(Year 1964) 

Railway route miles 244 
Tube 66 
Sub-surface 22 
Surface 156 

Passenger traffic — railway 
Journeys 674 million 
Average length 4.55 miles 
Passenger miles 3,066 million 

Passenger traffic — road 
Journeys 2,252 million 
Average length 2.26 miles 
Passenger miles $,094 million 

Vehicles 12,521 
Railway motor cars 2,905 
Railway trailer cars 1,269 
Total railway 4,174 
Omnibuses 8,347 

Staff 73,739 
Administrative, etc. §,582 
Civil engineering 5,134 
Electrical eng. 1,714 
Mech. eng. — railway 4,310 
Mech. eng. — road 9,152 
Railway operations 8,930 
Road operations 35,946 
Other 2,971 


an. 

Some London Transport Statistics 
(Year 1964) 

Railway route miles@244 
Tube © 66 

Sub-surface © 22 

Surface © 156 

-sp .5 

T& 

Ir 

ar. 

Passenger traffic \- railway 
Journeys © 674 million 
Average length @®4.55 miles 
Passenger miles © 3,066 million 
-T& 

Ir 

ar. 

Passenger traffic \- road 
Journeys ®2,252 million 
Average length @®2.26 miles 
Passenger miles @5,094 million 


“sp .5 

Vehicles @ 12,521 

Railway motor cars @2,905 
Railway trailer cars © 1,269 
Total railway ©4,174 
Omnibuses ® 8 ,347 

.T& 

In 

an. 

-sp .5 

Staff © 73,739 
Administrative, etc. 05,582 
Civil engineering 5,134 
Electrical eng. ©1,714 
Mech. eng. \- railway ©4,310 
Mech. eng. \- road@9,152 
Railway operations © 8,930 
Road operations © 35,946 
Other ©2,971 

JTE 
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Output: 


Some [nteresting Places 
Name Description Practical Information 
American Muse- | The collections fill 11.5 | Hours 10-5, ex. Sun 11-5, Wed. to 9 
um of Natural | acres (Michelin) or 25 } Location Central Park West & 79th St. 
History acres (MTA) of exhibi- | Admission | Donation: $1.00 asked 
tion halls on four floors. | Subway AA to 81st St. 
There is a full-sized re- | Telephone | 212-873-4225 
plica of a blue whale 
and the world’s largest 
star sapphire (stolen in 
| | 1964). | 
Bronx Zoo About a mile long and Hours 10-4:30 winter, to 5:00 sum | 
largest zoo in America. mer 
A lion eats 18 pounds of Location 185th St. & Southern Blvd. | 
meat a dav while a sea Grouse: 
lion eats 15 pounds of Admission | $1.00, but Tu,We,Th free 
fish. Subway 2. S to East Tremont Ave. ) 
Telephone 212-933-1759 
oe Ea 1 
Brooklyn Museum | Five floors of galleries | Hours Wed-Sat, 10-5, Sun 12 5 ! 
contain American and | Location Eastern Parkway & Washing: 
ancient art. There are ton Ave. Brooklyn. | 
American period rooms | Admission | Free 
and architectural orna- Subway 2,3 to Eastern Parkway. 
ments saved from wreck- Telephone 718-638-S000 
ers, such as a classical 
figure from Pennsylvania 
Station. 
New-York Histor- | All the original paintings | Hours Tues-Fri & Sun, 1-5; Sat 10-5 
ical Society for Audubon’s Birds of | Location Central Park West & 77th St 
America are here, as are | Admission | Free 
exhibits of American | Subway AA to Bist St. 
decorative arts, New | Telephone | 212-873-3400 
York history, Hudson 
River school paintings, 
carriages, and glass pa- 
perweights. 


Input: 


TS 
box; 
ch & & <5 
clele s 


Itiw(.75i) | Itw(1.5i) | Ip8 | Iw .25i)ps. 
Some Interesting Places 


Name © Description © Practical Information 


TL 


American Museum of Natural History 
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TI OTL 

The collections fill 11.5 acres (Michelin) or 25 acres (MTA) 
of exhibition halls on four floors. There is a full-sized replica 
of a blue whale and the world’s largest star sapphire (stolen in 1964). 
T} © Hours @ 10-5, ex. Sun 11-5, Wed. to 9 

\7 ©O\* DLocationD T{ 

Central Park West & 79th St. 

T} 

\* ®\* © Admission © Donation: $1.00 asked 

\* ©®\* @Subway D AA to 81st St. 

\* O\7* © Telephone © 212-873-4225 


Bronx Zoo@T{ 

About a mile long and .6 mile wide, this is the largest zoo in America. 
A lion eats 18 pounds 

of meat a day while a sea lion eats 15 pounds of fish. 
T} © Hours 0 T{ 

10-4:30 winter, to 5:00 summer 

T} 

\*7 O\* ©Location © T{ 

185th St. & Southern Blvd, the Bronx. 

T} 

\* ©\* © Admission © $1.00, but Tu, We,Th free 
\* O©\* OSubway ©2, 5 to East Tremont Ave. 

\* ©\* © Telephone © 212-933-1759 


Brooklyn Museum © T{ 

Five floors of galleries contain American and ancient art. 

There are American period rooms and architectural ornaments saved 
from wreckers, such as a classical figure from Pennsylvania Station. 
T} © Hours © Wed-Sat, 10-5, Sun 12-5 

\7 ®\7 © Location © T{ 

Eastern Parkway & Washington Ave., Brooklyn. 

T} 

\* ©®\* D Admission ® Free 

\* ©\* OSubway ©2,3 to Eastern Parkway. 

\* O\* © Telephone © 718-638-5000 


Tt 

New-York Historical Society 

T} OTL 

All the original paintings for Audubon’s 

I 

Birds of America 

-R 

are here, as are exhibits of American decorative arts, New York history, 
Hudson River school paintings, carriages, and glass paperweights. 
T} © Hours OTL 

Tues-Fri & Sun, 1-5; Sat 10-5 

T} 

\* ®\* © Location OTL 

Central Park West & 77th St. 

T} 

\* ®\* © Admission © Free 

\* ©\* OSubway © AA to 81st St. 

\* ©\* © Telephone © 212-873-3400 

Sle 
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Output: 


Name 
Holmdel 
Murray Hill 
Whippany 
Indian Hill 


Input: 


-TS 
expand; 
cSSs 
cece 
linn. 


Bell Labs Locations 


Address 
Holmdel, N. J. 07733 
Murray Hill, N. J. 07974 
Whippany, N. J. 07981 
Naperville, Illinois 60540 


Bell Labs Locations 
Name @® Address © Area Code © Phone 
Holmdel ® Holmdel, N. J. 07733 ©201 ©949-3000 


Murray Hill © Murray Hill, N. J. 07974 ©201 ©582-6377 


Area Code 
201 
201 
201 
312 


Whippany © Whippany, N. J. 07981 ©201 ©386-3000 
Indian Hill ® Naperville, Illinois 60540 ©312 © 690-2000 


.TE 


Acknowledgments 


Phone 
949-3000 
582-6377 
386-3000 
690-2000 


Many thanks are due to J. C. Blinn, who has done a large amount of 
testing and assisted with the design of the program. He has also writ- 
ten many of the more intelligible sentences in this document and 


helped edit all of it. 


All phototypesetting programs on UNIX are 


dependent on the work of J. F. Ossanna, whose assistance with this 
program in particular has been most helpful. This program is pat- 
terned on a table formatter originally written by J. F. Gimpel. The 
assistance of T. A. Dolotta, B. W. Kernighan, and J. N. Sturman is 
gratefully acknowledged. 
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List of Tb! Command Characters and Words 


Command 
aA 
allbox 
bB 

box 

cc 
center 
doublebox 
eE 
expand 
fF 

il 

1L 

nN 

NHN 

pP 

rR 

sS 


Meaning 
Alphabetic subcolumn 
Draw box around all items 
Boldface item 
Draw box around table 
Centered column 
Center table in page 
Doubled box around table 
Equal width columns 
Make table full line width 
Font change 
Italic item 
Left adjusted column 
Numerical column 
Column separation 
Point size change 
Right adjusted column 
Spanned item 
Vertical spanning at top 
Change data separator character 
Text block 
Vertical spacing change 
Minimum width value 
Included troff command 
Vertical line 
Double vertical line 
Vertical span 
Vertical span 
Double horizontal line 
Horizontal line 
Short horizontal line 
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Section 
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14 


S/1280 Inter-CPU Communication 


The /nter-CPU Communication facility (ICC) provides communication 
between programs running on S/1280's various CPUs. The system 
kernels running on the various Application Processors use ICC to 
coordinate with each other and with CTOS; this permits these kernels 
to act as a single CTIX kernel. 


CTIX processes can use ICC to communicate with each other or with 
CTOS system services. If both processes participating are CTIX 
processes, ICC is simply an enhanced communication facility and it 
does not matter whether the two processes actually run on different 
CPUs. If one of the processes provides a CTOS system service, ICC is 
a means to use CTOS controlled resources directly, without working 
through the CTIX kernel. 


Processes need no special status or permissions to use ICC. Fach ICC 
action is executed by a CTIX system call. 


The important concept behind ICC is that processes provide other 
processes services. For example, a database service permits the 
storage and retrieval of records; a spooling service queues files. 


ICC labels CTIX processes by the roles they play in ICC communica- 
tions. A server is a process that provides a service; a client is a pro- 
cess that uses a service. For example, users might run query pro- 
grams to specify retrievals. The query programs send messages to a 
database management service; the program in charge of the database 
does the actual retrieval. The query programs are clients of the data- 
base management service; the retrieval program is the server for the 
database management service. These labels are only valid in reter- 
ence to a particular service: a server for one service might be a chent 
of another service. 


S/1280 Inter-CPU Communication 14° 1 


Each ICC interaction consists of two messages. A request is a mes- 
sage from a client to a server. A response is a return message from a 
server to a client. A server must provide a response to each request. 


Clients and servers do not address each other directly. A client speci- 
fies that a message is a request to a specific service; the kernel sends 
the request to whatever server provides that service. A server speci- 
fies that a message is a response to a specific request; the kernel sends 
the response the sender of that request. 


Points of View 


When a process uses ICC it plays the role of client or server. This 
role affects the way the process views ICC. Here we summarize the 
points of view. For the moment, we assume a process has but one 
point of view. 


The Client 


There are actually two kinds of client. The basic client uses a simpli- 
fied system call that is adequate for most uses. The general client has 
a complicated repertoire of system calls. 


A basic client sends a single message and waits for its response. This 
action requires a single system call that dispatches the request, waits 
for the response, and copies the response (Figure 14-1). 


A general client can send any number of messages at a time. It 
manages the resulting responses with one or more message queues 
(Figure 14-2). The client must periodically examine these queues 
and delete responses from them. 
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Figure 14-1. A Basic Client 
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Figure 14-2. A General Client 
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A basic client actually possesses a response queue just like that of a 
general client. The kernel manages the queue on the client’s behalf. 


The Server 


A server manages its incoming requests with one or more request 
queues (Figure 14-3). Every request for a particular service goes to a 
specific request queue. A server that provides more than one service 
can use one request queue or several. 


A server need not respond to requests in the order it receives them, 
but it must respond to every request. 
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Figure 14-3. A Server 
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Exchanges 


Clients and servers manage their message queues via exchanges. One 
exchange handles each queue. When a client sends a request, it tells 
the kernel to queue the resulting response at a specific exchange. 
When a server wants to provide a service, it tells the kernel to queue 
requests for that service at a specific exchange. A process specifies 
an exchange when it asks the kernel for newly queued messages. 


A Note on Source Code 


This section mentions several standard structure types and constants. 
CTIX provides a C version of these definitions in /usr/include/exch.h. 
In a C ICC program, include this file with 


#include <exch.h> 
Programmers who work in languages other than C should sce the 


appropriate language manual for definitions of equivalent data struc- 
tures. 


The Basic Client 


For the basic client, each ICC interaction has three steps: 
e Describing the request with the request block. 
e Calling the service. 


e Examining the response. 


The Request Block 


A client describes a request with a data structure called a request 
block (Figure 14-4). ICC requires that each request begin with a 
standard group of fields called a request header. A server can require 
additional data fields. We will discuss the data fields first. 


A request block contains three groups of data fields: 
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e Control information is data that the client sends to the server by 
placing it in the request block. The control information 
immediately follows the request header. 


e Request PbCbs immediately follow the control information. 
Each request PbCb specifies the beginning of and length of a 
block of data. This data is sent to the server. 


e Response PbCbs immediately follow the request PbCbs. Each 
response PbCb specifies the beginning and length of a block of 
unused memory. Response data goes into this memory. 


A pointer to bytes/count of bytes (PbCb) describes a data area outside 
the request block. The user include file defines a PbCb this way: 


struct PbCb { 
char *pc_offset; 
unsigned short pc_count; 
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Figure 14-4. A Basic Client’s Request to JEEVES 
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Some servers are rigid as to the number and kind of data fields. A 
CTOS server, in particular, must always have a specific number of 
control information bytes, request PbCbs, and response PbCbs. Be 
sure to follow the data field rules specified for the service. 


The include file defines a request header thus: 


struct rqheader { 
unsigned short r_sCntInfo; 
unsigned char r_nReqPbCb; 
unsigned char r_nRespPbCb; 
unsigned short r_userNum; 
unsigned short r_exchResp; 
unsigned short r_ercRet; 
unsigned short r_rqCode; 

+5 


The client does not set r_userNum or r_ercRet. The other fields 
require the following values: 


r_sCntInfo Number of bytes of control information. 
r_nRegPbCb Number of request PbCbs. 
r_nRespPbCb Number of response PbCbs. 


r_exchResp The response exchange descriptor. The definition of 
this term is not important to a basic client. Set 
r_exchResp to the value returned by ExQueryD- 
fltRespExch (no arguments). We will define 
response exchange descriptor when we get to general 
clients. 


r_rqCode The request code. This specifies the service 
addressed. 


Example 


Suppose that a service is identified by the constant JEEVES. JEEVES 
requires two bytes of control information, one request PbCb, and one 
response PbCb. A client of JEEVES might declare the request block 
thus: 
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struct jblock { 
struct rqheader jheader; 
short jcinfo; 
struct PbCb reqdata; 
struct PbCb respdata; 

} jmess; 


The client sends 13 in the control data and a string name as request 
data. The client provides an array respdata for the response data. 
The following code sets up the request block: 


jmess.jheader.r_sCntInfo = 2; 
jmess.jheader.r_nReqPbCb = 1; 
jmess.jheader.r_nRespPbCb = 1; 
jmess.jheader.r_exchResp = exQueryDfltRespExch(); 
jmess. jheader.r_rqCode = JEEVES; 

jmess.jcinfo = 13; 

jmess.reqdata.pc_offset = name; 
jmess.reqdata.pe_count = strlen(name); 
jmess.respdata.pc_offset = respdata; 
jmess.respdata.pe_count = sizeof(respdata); 


Call the Service 


ExCall sends a request block to a service and waits for a response. 
This system call is defined thus: 


exCall(reqblp); 
struct rqheader *reqblp; 


Reqblp must point to the request block that describes the request. If 
the kernel succeeds in sending the request and obtaining a response, 
exCall returns 0. If the kernel cannot send the message, exCall 
returns -1 and sets the external variable errno. 
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Example 


This call passes sends the JEEVES request block: 


if (exCall(&jmess) == -1) { 
perror(‘‘can’t send message’’); 

exit(1); 

+ 


The Modified Request Block 


A successful use of exCall modifies the request block. This provides 
the error return code and response data from the server: 


e R_ercRet in the request header contains the server’s return 
code. Conventionally, a zero return code means that the 
server performed the client’s service. 


e Each region of memory described by a response PbCb contains 
response data from the server. If a server provides more data 
than the client allowed for, the kernel right-truncates the 
server data to fit. ICC conventions do not provide a way for 
the server to tell the client the amount of response data actu- 
ally sent; the server’s own conventions must provide for this, if 
necessary. 


Figure 14-5 shows how a response from JEEVES modifies the client's 
request block. 


The General Client 


The general client takes separate action to issue requests and to 
receive responses. This section describes requests and responses as 
separate issues—but remember that each request produces a response. 
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Figure 14-5. Request Block Modified by Response From JEEVES 


The Request Side 


The general client describes its request with a request block. This 
request block has the same format as a request block used by a basic 
client, but two fields change in function: 


e R_exchResp in the request header. This must be an exchange 
descriptor. If a client only uses one response queue, it can use 
the exchange descriptor returned by exQueryDfltRespExch. If 
a client uses more than one response queue, it must allocate 
additional exchanges with exAllocExch (no arguments). The 
kernel will queue the response to this request at the exchange 
indicated by r_exchResp. 
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e The client need not specify the pc_offset fields in the response 
PbCbs: the kernel ignores them. It is still important to put 
the data area sizes in the pc_count fields: the kernel passes 
this data to the server. 


Figure 14-6 shows a general client’s request to JEEVES. 


The general client sends requests with exRequest, which is defined 
thus: 


unsigned short exRequest(reqblp); 
struct rqheader *reqblp; 


As with exCall, reqblp points to a request block that describes the 
request. 
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Figure 14-6. A General Client’s Request to JEEVES 


ExRequest returns a request descriptor. The request descriptor 
uniquely identifies the request and its response in subsequent dialo- 
gues between the client and the kernel. 


ExRequest copies the request block before it returns. Thus the client 
can safely modify or deallocate the request block once ExRequest 
returns. 
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Example 


The general client version of our JEEVES example uses the following 
call: 


if (rqdes1 = exRequest(&jmess) == RQDES_INVALID) { 
perror(‘‘can’t send message’’); 
exit(1); 

} 


This call copies jmess and the request data area and sends them to 
the server. It leaves jmess unaltered. The ICC include file defines 
RQDES_INVALID, a value that cannot be a valid request descriptor. 


The Response Side 


Responses queue up at the client's exchanges in the order the servers 
send them. This order may not correspond to the order in which the 
client sent the requests. 


The general client discovers the current contents of the queue by 
doing a series of checks on the exchange. The first check tells the 
client about the oldest response in the queue; the second check tells 
about the second-oldest response, and so on. When the client sees a 
response it wants to read, it must copy it from the queue; this 
removes the response from the queue and makes subsequent checks 
start over with the oldest response still on the queue. 


There are two ways to do checks. They differ only in their action 
when their are no new responses to report on: 


e ExCheck checks the queue. If there are no new responses 
(responses that are not yet returned to a wait or check), it 
returns immediately with the value -1 and sets the external 
variable errno to ENOMSG. 


@ ExWait checks the queue. If there are no new responses 
(responses that are not yet returned to a wait or check), it 
waits until a new response arrives. 


These are the definitions of exCheck and exWait: 
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exCheck(exch, mstat); 
unsigned short exch; 
struct msgret *mstat; 


exWait(exch, mstat); 
unsigned short exch; 
struct msgret *mstat; 


Exch is the exchange descriptor; mstat points to a structure to which 
the kernel writes a report on the message. ExCheck and exWait 
return -1 on error or failure. 


This is the definition of the msgret structure in the include file. 


struct msgret { 
unsigned short m_rqCode; 
unsigned short m_reqdest; 
int m_size; 
char m_filag; 
unsigned short m_ercRet; 
unsigned char m_cputype; 
unsigned char m_slot; 
struct rqheader *m_offset; 
5 


When exCheck or exWait report on a new response, the returned 
msgret structure looks like this: 
m_rqCode _ The service that is responding. 


m_reqdest The request descriptor. This is the same value the 
client got from exRequest when it sent the request. 


m_size Size of the response. This is the size of the request 
block, plus the sizes of any response data blocks, plus 
the number of bytes used to make the response data 
blocks begin on even addresses. 


m_flag The value MRESPONSE. 


m_ercRet The server's error return code. This is same value that 
is in r_ercRet in the response header. 


The remaining fields give information on the physical location of the 
message and its host CPU. 


If a general client wants to copy the response, it must set up a request 
block to receive the data. This block has the same format and data 
as the one passed to exRequest. In addition, the client must provide 
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the address of each response data area; this goes in the pc_count 
fields of each response PbCb. 


The response area sizes need not be the same sizes specified in the 
request: the client may want to specify bigger areas if the size of the 
response (m_size in the msgret structure) indicates that the server 
ignored the client’s original response data maximums. In any case, 
the kernel right-truncates any response data blocks that will not fit the 
client’s areas. 


It is reasonable for a client to set up a single request block, with com- 
plete response PbCbs, and use this block both for sending the request 
and for copying the response. 


Example 


Figure 14-7 shows a request block ready to receive a response from 
JEEVES. 
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Figure 14-7. Ready for Response from JEEVES 
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Reqdes is the same request descriptor returned by exRequest and in 
m_reqdes in the response’s msgret structure. 


The exCpResponse system call copies a response: 


exCpResponse(reqdes, reqblp) 
unsigned short reqdes; 
struct rqheader *reqblp; 


Reqdes is the request descriptor; reqblp points to the request block 
that is to receive the reply. The kernel modifies, 

e r_ercRet in the header to the server's return code; 

e each data area indicated by a response PbCb. 


ExCpResponse modifies the same request block fields as does exCall. 
See Figure 14-5 


Mixing General and Basic Roles 


A single client can use both exCall and exRequest. A response to an 
exCall request is handled separately from other responses going to the 
same exchange. ExCall does not affect the status of any message 
anywhere, except its own request and response. 


The Server 


The server behaves very much like the general clicnt: it monitors 
queues of incoming messages (requests) and it has a single, indepen- 
dent, stream of outgoing messages (responses). To receive requests, 
the process must associate an exchange with a request code. 


Choosing the Request Code 


Convergent Technologies reserves all request codes less than 49152 
(OxC000). Any service you add must have a request code between 
49153 (OxC001) and 65535 (OxFFFF). 


Choose new request codes in as few continuous sequences as you can. 
Each continuous sequence of request codes requires a certain amount 
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of overhead in certain system tables. It is very easy to fill up these 
tables. 


Setting Up the Service 


A server, like a general client, must provide one exchange for each 
message queue. It can use the standard exchange specified by 
ExQueryDfltRespExch, or it can allocate additional exchanges with 
ExAllocExch. 


A server then assigns each of its exchanges one or more services. It 
does this with exServeReq: 


exServeReq(exch, code) 
unsigned short exch; 
int code; 


Exch is an exchange descriptor. Code is the request code for the ser- 
vice. The first process to specify a request code with exServeReq is 
the only server for that request code. 


The Request Side 


The server, like the general client, monitors its message queues with 
exCheck or exWait. ExCheck and exWait deal with request queues 
in precisely the way they deal with response queues. We must, how- 
ever, take a second look at the msgret structure. 


m_rqCode The request code specified by the client. This distin- 
guishes services when a single exchange is associated 
with more than one service 


m_reqdest The request descriptor. This uniquely identifies the 
request and its response in subsequent server system 
calls. 


m_size Size of the request. This is the request block, plus any 
request data, plus any padding to make blocks of 
request data appear at even addresses. 


m_flag The value MREQUEST. 


m_ercRet No useful value. 
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The values in the other fields serve no purpose in the current imple- 
mentation. 


The server must dispose of each request on the queue. The exCpRe- 
quest call copies a request: 


exCpRequest(reqdes, reqb!p) 
unsigned short reqdes; 
struct rqheader *reqblp; 


As with exCpResponse, exCpRequest removes the message from the 
queue and restarts at the oldest “essage subsequent checking on the 
queue. 


ExCpRequest copies the message to the memory pointed to by 
reqblp; reqblp must be an even address. ExCpRequest puts the 
request data blocks directly after the request block; each data block 
begins at an even address. ExCpRequest modifies the request PbCbs 
so that they describe the new copies of the request data blocks. With 
this exception, the request block and data blocks all contain the values 
placed in them by the client. The response exchange descriptor and 
response data pointers, however, are meaningless to the server. 


Example 


The JEEVES server is run when the system first comes up. It begins 
by appropriating its request code: 
ex = ExQueryDfitRespExch(); 
if (exServeReq(ex, JEEVES) == -1) { 
perror(‘‘JEEVES server: can’t get request code’’); 
exit(1); 
} 


The server must then periodically check its exchange. When it dis- 
covers a request it wants to deal with, the server copies the request: 


jmess = (struct jblock *) malloc(mstat.m_size) 
exCpRequest(mstat.m_reqdest, jmess); 


Figure 14-8 shows a request received by the JEEVES server. 
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The Response Side 


The server uses a request block to describe a response. It sets 


e R_ercRet in the request block header. This indicates the 
return code. 
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Figure 14-8. Request Copied by JEEVES Server 
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It is reasonable, but not necessary, for a server to use the same 
request block that it copied from its request queue. 


The server sends the response with exRespond: 


exRespond(reqdes, reqblp) 
unsigned short reqdes; 
struct rqheader *reqblp; 
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Figure 14-9. JEEVES Server Ready to Send Response 


Reqdes is a request descriptor that indicates which request provoked 
the response. Reqblp points to the request block that describes the 
response. 


Example 


Figure 14-9 shows a response set up by the JEEVES server. 


Mixing Roles 


A process that provides one or more services (playing the role of 
server) may use other services (playing the role of client). It is all 
right for such a process to use a single exchange for both requests and 
responses. On such an exchange, the requests and responses form a 
single queue of messages. 
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The mixed-role process must apply exCpRequest and exReject only to 
requests and exCpResponse only to responses. 


Note that exCall does not affect the status of any waiting request or 
response. 


Example 


exServeReq(exchange = ExQueryDfltRespExch(), JEEVES); 
for G;) ¢ 

exWait(exchange, &mstat) 

switch (mstat.m_flag) ¢ 


case MREQUEST: 


inblock = alloc(mstat.msize); 
exCpRequest(mstat.m_reqdes, inblock); 


(action on request, including exRespond) 


break; 


case MRESPONSE: 
exCpResponse(mstat.m_reqdes, outblock); 


(action on response) 


break; 


Simplified Access to a Request Queue 


Most servers will normally do an exWait, followed closely by an 
exCpResponse. These two actions are combined in exGetNext. It is 
different from a simple exWait/exCpResponse sequence in the follow- 
ing ways: 
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e It ignores responses. 
e It is a single system call. This saves work by the kernel. 


e Like exCall, it does not affect the status of any messages it 
does not copy. 


ExGetNext takes the following form: 


exGetNext(exch, reqblp, size) 
unsigned short exch; 

struct rqheader *reqblp; 
unsigned short size 


where 
exch is the descriptor for the exchange of interest; 
reqblp points to the buffer that is to receive the message; 
size is the size of the buffer. 


Any message that is too big for the buffer is right-truncated to fit. 


Message Queue Access Summary 


This section summarizes how a process accesses the messages in a 
message queue. Note that first-in first-out (FIFO) access is simplest, 
but not mandatory. 


FIFO access to a message list occurs only when a process follows each 
check of the exchange (exCheck or exWait) with a copy (exCpRe- 
quest, exCpResponse) or disposal of the newly discovered message. 


A process can thumb through the msgret structures for the entire 
message queue simply by not copying or discarding any message at 
the exchange between checks. Repeated calls to exCheck return suc- 
cessively newer msgret structures until there aren't any more; 
repeated calls to exWait return successively newer msgret structures 
forever. 


Any copy or discard on a message waiting at an exchange resets the 
procedure for that exchange: subsequent checks start over with the 
oldest message. 


ExCall, however, ignores all messages except the request it sends and 
the response it waits for and copies; ExGetNext ignores all messages 
except the request it copies. 
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One can think of each message as having a “‘noticed’’ flag. A suc- 
cessful exCheck or exWait always notices the oldest message whose 
“noticed” flag is off. The following events affect this flag: 


e The message’s arrival at the queue turns that message’s 
“noticed” flag off. 


e An exCheck or exWait that notices a message turns that 


eK 


message’s ‘‘noticed’’ flag on. 


e An exCpResponse or exCpRequest on a message in a queue 
turns off the ‘‘noticed’’ flag of every message in the queue. 


ExCall and exGetNext do not affect the noticed flag of any message. 


Releasing Unwanted Exchanges 


All processes share a finite pool of exchanges. A process’s death 
automatically deallocates its exchanges. A process that will continue 
working but has no further use for an exchange should relinquish it 
with exDeallocExch: 


exDeallocExch(exch) 
unsigned short exch; 
Exch is the descriptor of the unwanted exchange. 


The death of a process deallocates all its exchanges. Process death is 
the only way to deallocate the default response exchange. 


The kernel has standard actions for messages still waiting at an 
exchange when the exchange is deallcoated. The kernel discards any 
responses still waiting at the deallocated exchange. The kernel issues 
an exReject on any requests still waiting at the deallocated exchange: 


exReject(rd, ercServiceNotAvail); 


where rd is the request’s request descriptor, and ercServiceNotAvail 
is a constant defined in the include file. 
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Setting Final Action 


The deallocation of a request’s exchange may be a signal that the 
request is obsolete. For example, a client might terminate suddenly 
before its server has acted on a particularly time-consuming request. 
It is useful for a client to prepare, in advance, messages that indicate 
that it is no longer able to wait for a response. ExSendOnDealloc 
provides a way to tie a request to the deallocation of a particular 
exchange. 


exSendOnDealloc(reqblp) 
struct rqheader *reqblp; 


This call specifies a final request. Reqblp points to the request block; 
exSendOnDealloc returns a request descriptor. ExSendOnDealloc 
causes the kernel to copy the final request indicated by reqblp; but 
the kernel does not immediately queue the request at the server's 
exchange. The status of the final request’s response exchange con- 
trols the final request: when this exchange is deallocated, the kernel 
queues the final request. Thus the client dispatches the final request 
either by dying or by a call to exDeallocExch. 


Note that a server must respond to a final request, even though the 
client will never read the response. 


A client can cancel a final request: 


exCnxSendOnDealloc(req) 
unsigned short req; 


Req is the request descriptor from the call to exSendOnDealloc. 


Summary of System Calls 


Here is a complete summary of ICC system calls. On error or failure, 
all these calls return -1 and set the external variable errno. Only 
those functions indicated return a useful value on success. For errno 
values, see iniro(3) and perror(3) in the MegaFrame CTIX Operating 
System Manual. Always test for equality with -1: some calls return 
valid negative values. Only indicated functions return useful values 
on success. 
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Obtain and abandon exchanges. 


exQueryDfltRespExch() 
Returns the exchange descriptor for the default response 
exchange. Despite the name, you must specify this exchange 
explicitly, and you can accept requests on a default response 
exchange. 


exAllocExch() 
Allocates an exchange and returns the exchange descriptor. 


exDeallocExch(ex) 
unsigned short ex; 
Deallocates the exchange specified by ex. 


Call a server. 


exCall(reqblk) 

struct rgheader *reqblk; 
Sends the request described by request block reqblk; waits for 
the response; copies the response. ExCall ignore all messages 
except its own request and response. 


Send a message. 


exRequest(reqblp) 

struct rqheader *reqblp; 
Transmits the request described by request block reqbl. 
Returns a request descriptor. 


exRespond(reqdes, reqblp) 

unsigned short reqdes; 

struct rqheader *reqblp; 
Transmits a response to the request indicated by reqdes. 
Reqblp describes the response. 


Check for waiting messages. 


exWait(ex, mstat); 

unsigned short ex; 

struct msgret *mstat; 
Gets status structure for oldest unnoticed message waiting at 
exchange specified by ex. ExWait writes the status structure 
to the location pointed to by mstat. If there are no unnoticed 
messages at the specified exchange exWait waits until there 
are. 
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exCheck(ex, mstat); 

unsigned short ex; 

struct msgret *mstat; 
Gets status structure for oldest unnoticed message waiting at 
exchange specified by ex. ExCheck writes the status structure 
to the location pointed to by mstat. If there are no messages 
at the specified exchange, exCheck sets errno to ENOMSG 
and returns -1. 


A successful exWait or exCheck marks the discovered message 
as ‘“‘noticed’”’: subsequent checks on the same exchange pro- 
duce only newer messages. Any disposal of a message waiting 
at an exchange (exCpRequest, exCpResponse, exReject, but 
not exCall or exGetNext) marks all messages on the exchange 
as “‘unnoticed”’: subsequent checks on the exchange start over 
with the very oldest message on the exchange. 


Dispose of a response. 


exCpResponse(reqdes, reqst) 
short reqdes; 
struct request *reqst; 
Copies the response indicated by reqdes. 


Dispose of a request. 


exCpRequest(reqdes, reqst) 

unsigned short reqdes; 

struct request *reqst; 
Does not copy the request indicated by reqdes; sets the 
request’s return code field to code and sends the message back 
as a response. ExReject does not permit the server to examine 
the control data or other request fields. 


Get the next request. 


exGetNext(exch, reqblp, size) 

unsigned short exch; 

struct rqheader *reqblp; 

unsigned short size 
Copies the oldest request waiting at exch to reqblp. If the 
request is more than size bytes, it is right-truncated. 
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Set final action. 


short exSendOnDealloc(reqblk) 

struct rqheader *reqblk; 
Reads the request described by the request block pointed to by 
reqblk, but doesn’t send it until this process dies or otherwise 
deallocates the request’s response exchange. Returns a request 
descriptor that is only good for cancelling the request. 


A Note on Communicating with CTOS 


Integer value conversion is necessary if client and server don’t both 
run under CTIX. CTIX runs on Application Processors, which are 
based on the Motorola 68010 and 68020. CTOS runs on all others 
S/1280 processors, which are based on the INTEL 80186. Motorola 
and INTEL use opposite byte ordering for integer values. ICC does 
this conversion automatically for the request block header. For 
integers in the control information and in the request and response 
data, the programmer must do the conversion. See swapshort(3C) in 
the MegaFrame CTIX Operating System Manual. 


CTIX ICC for the CTOS Programmer 


ICC differs in important ways from its CTOS counterpart, Inter- 
Process Communication (IPC). For the benefit of programmers 
whose previous experience is with CTOS, we summarize these differ- 
ences. 


System Primitives 


Most of the differences between ICC primitives and IPC primitives 
reflect an important difference between CTIX and CTOS: CTIX 
processes cannot access each other’s memory. Thus CTIX processes 
must send and receive copies of messages, not just pointers to mes- 
sages. 


ExCall provides services not available under CTOS. Its use is strongly 
encouraged because it requires less work by the CTIX kernel. 
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CTIX does not support an equivalent of Send or Psend. 


Exchanges and Messages 


A CTIX exchange can serve as both request and response exchange. 


A CTIX exchange identifier is called an exchange descriptor. Unlike 
CTOS identifiers, descriptors are not unique, except among exchanges 
owned by the same process. 


Each CTIX exchange belongs to a specific process. Only the 
exchange’s owner can receive messages at that exchange. 


The CTIX programmer is encouraged to use explicitly the default 
response exchange. Use of this exchange in asynchronous messages is 
perfectly safe. 


CTIX does not strictly enforce first-in-first-out access to an exchange’s 
messages. ExCall sends a request and then waits for the correspond- 
ing response, ignoring all other responses. A certain usage of exWait 
and exCheck (see ‘‘Message Queue Access Summary’’, above) gives a 
process random access to an exchange’s queue of messages. 
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Introduction 


This chapter is a CTIX system assembler user's guide for the 
Motorola 68010, 68020, and 68881. This chapter should be used in 
conjunction with the AYC68000 16. Bit Microprocessor User's Manual* 
the MC68020 32-Bit Microprocessor User's Manual**, and_ the 
MC68881 Floating-Point Coprocessor User's Manual}. Programmers 
familiar with the MC68010, MC68020, and MC68881 should be able 
to program in CTTX assembly language by referring to this chapter; 
however, this is not a manual for a processor itself. Details about the 
effects of instructions, meanings of status register bits, handling of 
interrupts, and many other issues are not dealt with here. 


NOTE 


This chapter refers to the MC68010, MC68020, and MC6S8881 
as “MCO68K” processors. ‘This chapter also refers to the 
MC68000 /6-Bir Microprocessor User's Manual, the MC68020 
32-Bit Microprocessor User's Manual, and the MC688&/ 
Floating-Point Coprocessor User's Manual as ““MCO68K_ user 
manuals,” 


* MC68000  16-BIT MICROPROCESSOR User's Manual, Third Edition: 
Faglewood Cliffs, N.J.: Prentice-Hall, 1982. 

** MC68020 32-BIT MICROPROCESSOR User's) Manual, Second Fdition, 
Englewood Cliffs, N.J.: Prentice-Hall, 1985. 

t MC68881 FLOATING-POINT COPROCESSOR User's Manual, First: Edition, 
1985. 
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Organization 


This section describes 
e how to invoke the assembler 
e general syntax rules and program organization 


e pseudo-operations, span-dependent optimization, and address 
modes 


e major differences between CTIX and other assemblers 


Table 15-3 presents all MC68K instruction formats alphabetically by 
operation. 


Use of the Assembler 


‘The C'TIX system command as invokes the assembler and has the fol- 
lowing syntax: 


as [-0 output | file 


This causes the named file to be assembled. The output of the assem- 
bly is left on the file ourpur specified by the -o flag. If no such specif- 
ication is made, the output is left in a file whose name is formed by 
removing the .s suffix, if there is one, from the input file name and 
appending an .o suffix. 


Vhe CTIX assembler, versions 5.0 and higher, supports flexnames. 
“Flexname” is the AT&T term for the feature that allows a program 
identifier to be longer than eight characters. The following are avail- 
able as backward compatibility options: the -T option to as, which 
truncates symbols to eight characters, and the -G option to Id, which 
changes the symbol name look-up algorithm. (Refer to as(1) and 
[d(1) in the CTIX Operating System Manual). 
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General Syntax Rules 


Assembler Code Elements 


Identifiers, registers, constants, and comments are basic elements that 
typically occur in CTIX assembly code. The following paragraphs 
describe each of these elements. 


Identifiers 


An identifier is a string of characters taken from the set a-z, A-Z, -. 
~, %, and 0-9. The first character of an identifier must be a letter 
(upper or lower case) or an underscore. Upper and lower case letters 
are distinguished. For example, 


con35 and CON35 


are two distinct identifiers. 
There is no limit on the length of an identifier. 


The value of an identifier is established by the set pseudo-operation 
or by using it as a label. (For more information on set pseudo- 
operations and labels, see “Symbol Definition Operations’ and 
“Location Counters and Labels,”’ respectively, below.) 


The tilde (~) has special significance to the assembler. A ~ used 
alone as an identifier means ‘“‘the current location.” A ~ used as the 
first character in an identifier becomes a ‘*.”’ in the symbol table. 
This allows symbols such as .eos and .Ofake to make it into the svm- 
bol table (as required by the Common Object File Format.) 


Registers 


An MC68K processor register is an identifier preceded by the charac- 
ter %, The predefined registers are 
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God Fd4 Ya Hat FO 4 Yce Yusp “isp 
Gal GdS Gal GaS Gil GS Gope %eaar Semsp 
Ged2  Gd6 Gad Gab G2 Ff Gsp Gocacr “sfc 
Gd3 GAT Gad Goal G3 GET Gesr Godfe  Sovbr 
“etp 


NOTE 


The registers Ya7 and Yesp represent the same machine regis- 
ter. Likewise, %a6 and %fp are equivalent. 


Constants 


The assembler deals with integer and floating-point constants. They 
may be entered as decimal, octal, hexadecimal, or character con- 
stants. Internally, the assembler treats all constants as 32-bit binary 
two's complement quantities or as floating point, where applicable. 


Numerical Constants. All numerical constants must be preceded by 
ampersand (&). Otherwise, the number is assumed to be an absolute 
address. 


A decimal constant is a string of digits beginning with a non-zero 
digit. 
An octal constant is a string of digits beginning with zero. 


A hexadecimal constant consists of the characters 0x or 0X followed 
by a string of characters from the set 0-9, a-f, and A-F. In hexade- 
cimal constants, upper and lower case letters are not distinguished. 


Floating point constants are preceded by Of. Double floating point 
constants are preceded by 0d. 


Examples of decimal, octal, hexadecimal, and floating point constants 
are listed as follows: 


set const, &35 # Decimal 35 

mov.w &035,%d1 # Octal 35 (decimal 29) 
set const, &0x35 # Hex 35 (decimal 53) 

mov.w &Oxff, Zod1 # Hex ff (decimal 255) 
fmov.] &0f123,%f0 # Floating point 123 
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Character Constants. All character constants must be preceded by 
ampersand (&). Character constants may be ordinary or special. 


An ordinary character constant consists of a single-quote (°) followed 
by an arbitrary ASCII character other than \. The value of the con- 
stant is equal to the ASCII code for the character. Special meanings 
of characters are overridden when used in character constants. For 
example, if ’# is used, the # is not treated as introducing a comment. 


A special character constant consists of ’\ followed by another charac- 
ter. All of the special character constants, and examples of ordinary 
character constants, are listed as follows: 


Constant Value Meaning 


&\b Qx08 Backspace 

&\t 0x09 Horizontal Tab 
&\n Ox0a Newline (Line Feed) 
& \v Ox0b ~—- Vertical Tab 

&\f OxO0c Form Feed 

&\r OxOd = Carriage Return 
&\\ OxSe — Backslash (\) 


&” 0x27 Single Quote 
&’0 0x30 = Zero 

&A Ox41 Capital A 
&'a Ox61 Lowercase A 


Comments 


Comments are introduced by the character # and continue to the end 
of the line. Comments may appear anywhere and are ignored by the 
assembler. (See also the discussion of the ident pseudo-operation in 
“Location Counter Control and Other Section Operations’ below. ) 


Format of Assembly Language Line 


Typical lines of CTIX assembly code look like: 
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# Clear a block of memory at location %a3 


text 2 
mov.w  &const,%d1 
loop: clr.1 (%a3)+ 
dbf Fo) loop # go back for const 


# repetitions 
init2: 
clr.1 count; clr.1 credit; clr.1 debit; 


These general points about the example should be noted: 


An identifier occurring at the beginning of a line and followed 
by a colon (:) is a label. One or more labels may precede any 
assembly language instruction or pseudo-operation. Refer to 
“Location Counters and Labels,’ below, for more informa- 
tion. 


A line of assembly code need not include an instruction. It 
may consist of a comment alone (introduced by #), a label 
alone (terminated by :), or it may be entirely blank. 


It is good practice to use tabs to align assembly language 
operations and their operands into columns, but this is not a 
requirement of the assembler. An opcode may appear at the 
beginning of the line, if desired, and spaces may precede a 
label. A single blank or tab suffices to separate an opcode 
from its operands. Additional blanks and tabs are ignored by 
the assembler. 


It is permissible to write several instructions on one line by 
separating them by semicolons. The semicolon is syntactically 
equivalent to a newline. A semicolon inside a comment is 
ignored. 


Program Organization 


A CTIX program is organized in section that are maintained and 
identified by location counters and labels, respectively. The following 
paragraphs describe sections, location counters, and labels. 


15—6 


Programmer's Guide: CTIX Supplement 


Sections 


A program in CTIX assembly language is normally broken into text, 
data, or bss sections. Instructions are usually placed in text sections, 
initialized data in data sections, and uninitialized data in bss sections. 
However, the assembler does not enforce this convention; for exam- 
ple, it permits intermixing of instructions and data in a text section. 


The assembler permits up to nine separate sections, three of which 
must be text, data, and bss. (User-defined sections and comment sec- 
tions are discussed below in ‘‘Location Counter Control and Other 
Section Operations.’’) The assembly language program may switch 
freely between them by using assembler pseudo-operations. (See 
“Location Counter Control and Other Section Operations,’ below.) 
When generating the object file, the assembler concatenates all sec- 
tions of the same name to generate a single section of that name. For 
example, if there are no section or ident pseudo-operations in the 
source file, the object file contains only one text section and one data 
section. 


There is only one bss section to begin with, and it maps directly into 
the object file. 


Because the assembler keeps together everything from a given section 
when generating the object file, the order in which information 
appears in the object file may not be the same as in the assembly 
language file. For example, if the data for a program consists of 


data 1 # section 1 
short Ox1111 

data 0 # section 0 
long Oxffffffff 

data 1 # section 1 
byte 0x2222 


then equivalent object code would be generated by 


dataO 
longOxffffffff 
short0Ox1111 
byte0x2222 
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Location Counters and Labels 


The assembler maintains separate location counters for each section. 
The location counter for a given section is incremented by one for 
each byte generated in that section. 


The location counters allow values to be assigned to labels. When an 
identifier is used as a label in the assembly language input, the 
current value of the current location counter is assigned to the identif- 
ier. The assembler also keeps track of which section the label 
appeared in. Thus, the identifier represents a memory location rela- 
tive to the beginning of a particular section. See ‘‘Location Counter 
Control and Other Section Operations,’’ below, for more information 
on values that are assigned to location counters. 


Types 


Identifiers and expressions may have values that are absolute, relocat- 
able, or undefined external types. 


In the simplest case, an expression (or identifier) may have an abso- 
lute value, such as 29, -5000, or 262143. 


An expression (or identifier) may have a value relative to the start of 
a particular section. Such a value is known as a relocatable value. 
The memory location represented by such an expression cannot be 
known at assembly time, but the relative values (i.e., the difference) 
of two such expressions can be known if they refer to the same sec- 
tion. Identifiers that appear as labels have relocatable values. 


If an identifier is never assigned a value, it is assumed to be an unde- 
fined external. Such identifiers may be used with the expectation that 
their values will be defined in another program, and hence known at 
load time; but the relative values of undefined externals cannot be 
known. 
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Expressions 


All constants are absolute expressions. An identifier may be thought 
of as an expression having the identifier’s type. For conciseness, the 
following abbreviations are used: 


abs _—_ absolute expression 
rel relocatable expression 
ext undefined external 


Expressions, except for floating point, may be built up from lesser 
expressions using the following operators: 


Add + 
Subtract = 
Multiply “ 
Divide { 
Left shift << 
Right shift >> 
Exclusive-OR - 
Bit $ 
One’s complement ! 
Modulus FG 
OR | 
AND RR 


Parentheses may be used to coerce the order of evaluation; otherwise 
the operators are evaluated, from highest to lowest precedence, us fol- 
lows: 


unary minus, !, Highest 
* 1, %% 

+, binary minus 

<<, >> 

&&, 1, 7 Lowest 


Division by zero is illegal. 


Expressions may be built up from lesser expressions using +, -, *, 
and / according to the following type rules: 
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abs + abs = abs 
abs + rel = rel + abs = rel 
abs + ext = ext + abs = ext 


abs — abs = abs 

rel— abs = rel 

ext — abs = ext 

rel — rel = abs, if the two relocatable expressions 
are relative to the same section 


abs * abs = abs 
abs / abs = abs 
—abs = abs 
Expressions using <<, >>, ~, $,!, %%, |, and && only make sense 


in absolute expressions. 


CAUTION 


Use of a rel-rel expression is dangerous, particularly when 
dealing with identifiers from text sections. The problem is 
that the assembler will determine the value of the expression 
before it has resolved all questions about span-dependent 
optimizations. Use this feature at your own risk! 


Pseudo-Operations 


Pseudo-operations establish values for identifiers and expressions. 
The following paragraphs identify data initialization, symbol defini- 
tion, location counter control, symbolic debugging, and switch table 
pseudo-operations. 


Data Initialization Operations 


Data initialization operations establish values for expressions. Each 
operation is presented by operation name, followed by the argument 
types and a description of the operation. 
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byte 


short 


long 


ASCII 


float 


double 


space 


abs,abs,... 


One or more arguments, separated by commas, may be 
given. The values of the arguments are computed to pro- 
duce successive bytes in the assembly output. 


abs,abs,... 


One or more arguments, separated by commas, may be 
given. The values of the arguments are computed to pro- 
duce successive 16-bit words in the assembly output. 


expr,expr,... 


One or more arguments, separated by commas, may be 
given. Each expression may be absolute, relocatable, or 
undefined external. A 32-bit quantity is generated for 
each such argument (for relocatable or undefined external 
expressions, the value may not be filled in until load 
time). 


string, string,... 


One or more strings may be given, separated by commas. 
The values of the arguments are computed to produce 
ASCII strings. 


fexpr,fexpr,... 


One or more arguments, separated by commas, may be 
given. The values of the arguments are computed to pro- 
duce 32-bit floating point values. fexpr is a floating point 
constant. 


fexpr,fexpr,... 


One or more arguments, separated by commas, may be 
given. The values of the arguments are computed to pro- 
duce 64-bit floating point values. fexpr is a floating point 
constant. 


abs 


The value of abs is computed, and the resultant number 
of bytes of zero data is generated. For example, 


space 6 
is equivalent to 
byte 0, 0, 0, 0, 0, 0 
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Alternatively, arguments may be bit-field expressions. A _ bit-field 
expression has the form 


n:value 
where both n and value denote absolute expressions. The quantity 
represents a field width; the low-order n bits of value become the con- 
tents of the bit-field. Successive bit-fields fill up 32-bit long quantities 
starting with the high-order part. If the sum of the lengths of the 


bit-fields is less than 32 bits, the assembler creates a 32-bit long with 
zeros filling out the low-order bits. For example, 


long4:-1, 16:0x7f, 12:0, 5000 


and 


long4:-1, 16:0x7f, 5000 


are equivalent to 


longOxf007£000, S000 


Bit fields may not span pairs of 32-bit longs. Thus 
long24:0xa, 24:0xb, 24:0xc 


yields the same thing as 


long0x00000a00, Ox00000b00, 0x00000c00 


Symbol Definition Operations 


Symbol definition operations establish values for identifiers. Each 
operation is presented by operation name, followed by the argument 
types and a description of the operation. 


set identifier,expr 


The value of identifier is set equal to expr, which may be 
absolute or relocatable. 


comm _ identifier,abs 


The named identifier is to be assigned to a common area 
of size abs bytes. If identifier is not defined by another 
program, the loader will allocate space for it. 
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The type of identifier becomes undefined external. 
Icomm _identifier,abs 


The named identifier is assigned to a local common of 
size abs bytes. This results in allocation of space in the 
bss section. 


The type of identifier becomes relocatable. 
global identifier 


This causes identifier to be externally visible. If identifier 
is defined in the current program, then declaring it global! 
allows the loader to resolve references to identifier in other 
programs. 


If identifier is not defined in the current program, the 
assembler expects an external resolution; in this case, 
therefore, identifier is global by default. 


Location Counter Control and Other Section 
Operations 


Location counter control operations establish values for location 
counters. Each operation is presented by operation name, followed 
by the argument types and the operation description. 


data abs 


The argument, if present, must evaluate to 0, 1, 2, or 3; 
this shows the number of the data section into which 
assembly is to be directed. If no argument is present, 
assembly is directed into data section 0. (Note that the 
abs argument may not be supported in future releases.) 


text abs 


The argument, if present, must evaluate to 0, 1, 2, or 3; 
this shows the number of the text section into which 
assembly is to be directed. If no argument is present, 
assembly is directed into text section 0. 


Before the first data or text operation is encountered, 
assembly is, by default, directed into text section 0. 
(Note that the abs argument may not be supported in 
future releases. ) 
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ident "comment string" 


This operation causes a comment section to be created if 
there is no comment section already and puts the comment 
string into the comment section. This is used for SCCS 
“what” strings [see whar(1) in the CTIX Operating System 
Manual]. 


(Not available on versions of the CTIX assembler previ- 
ous to 6.0.) 


section name," flag" 


This operation causes the creation of a new section, which 
is identified by name and has an attribute corresponding 
to flag. Attributes are defined in <sys/scnhdr.h>. The 
argument flag and associated attribute is one of the fol- 
lowing: 


STYP_BSS 
STYP_COPY 
STYP_INFO 
STYP_DSECT 
STYP_TEXT 
STYP_NOLOAD 
STYP_OVER 
STYP_LIB 
STYP_DATA 


NOTE: A new section is created as described above, but 
it is not loaded by the CTIX kernel unless there is an jfile 
for it and the ifile has been linked. (An jfile is an Id input 
file containing link editor command language scripts.) For 
information on creating an jfile, see “The Link Editor” in 
Programmer's Guide: UNIX System V. 


¢-osxanmtose 


(Not available on versions of the CTIX assembler previ- 
ous to 6.0.) 


org expr 


The current location counter is sect to expr. Expr must 
represent a value in the current section, and must not be 
less than the current location counter. 


even 


The current location counter is rounded up to the next 
even value. 
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align abs 


The argument must evaluate to 0, 1, 2, 3, or 4; this shows 
the alignment of the following instructions or data to the 
nearest abs byte boundary. For example, even is the same 
as align 2. 


Symbolic Debugging Operations 


The special assembler pseudo-operations, file and In, and the symbol 
attribute operations place debugging information into the object code 
file. This information typically includes line numbers and informa- 
tion about C language symbols, such as their type and storage class. 
The CTIX system C compiler generates symbolic debugging informa- 
tion when the -g option is used. Assembler programmers may also 
include such information in source files. 


file and In 


The file pseudo-operation passes the name of the source file into the 
object file symbol table. It has the form 


file ‘‘filename’”’ 


where filename consists of one to 14 characters. 


The In pseudo-operation makes a line number table entry in the 
object file. That is, it associates a line number with a memory loca- 
tion. Usually the memory location is the current location in text. 
The format is 


In line [,value] 
where line is the line number. The optional value is the address in 
the text, data, or bss section that is associated with the line number. 


The default when value is omitted (which is usually the case) is the 
current location in the text section. 
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Symbol! Attribute Operations 


The symbol attribute operations include basic symbolic testing and 
attribute-assigning pseudo-operations. 


Basic Symbolic Testing Operations. The basic symbolic testing 
pseudo-operations are def and endef. These operations enclose other 
pseudo-operations that assign attributes to a symbol and must be 
paired, as follows: 


def name 
# Attribute 
# Assigning 
: # Operations 
endef 


As an example, 
defx 
val-16 
scl1 
type06 
endef 


is equivalent to the C language statement 


int x; 


NOTE 


def does not define the symbol, although it does create a sym- 
bol table entry. Because an undefined symbol is treated as 
external, a symbol that appears in a def but never acquires a | 
value will eventually result in an error at link edit time. To 
allow the assembler to calculate the sizes of functions for other 
CTIX system tools, each def/endef pair that defines a function 
name must be matched by a def/endef pair after the function 
in which a storage class of -1 is assigned. 


Attribute-Assigning Operations. The attribute-assigning operations 
described below apply to the symbol name that appears in the opening 
def pseudo-operation in “Basic Symbolic Testing Operations,”* above. 
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val 


scl 


type 


tag 


line 


size 


dim 


expr 


Assigns the value expr to name. The type of the expres- 
sion expr determines with which section name is associ- 
ated. If value is ~, the current location in the text section 
is used. 


expr 


Declares a storage class for name. The expression expr 
must yield an ABSOLUTE value that corresponds to the 
C compiler’s internal representation of a storage class. 
The special value -1 designates the physical end of a func- 
tion. 


expr 


Declares the C language type of name. The expression 
expr must yield an ABSOLUTE value that corresponds to 
the C compiler’s internal representation of a basic or 
derived type. 


str 


Associates name with the structure, enumeration, or 
union named srr that must have already been declared 
with a def/endef pair. 


expr 


Provides the line number of name, where name is a block 
symbol. The expression expr should yield an ABSO- 
LUTE value that represents a line number. 


expr 
Gives a size for name. The expression expr must yield an 
ABSOLUTE value. When name is a structure or an 


array with a predetermined extent, expr gives the size in 
bytes. For bit fields, the size is in bits. 


expri, expr2,... 


Indicates that name is an array. Each of the expressions 
(exprl, expr2,...) must yield an ABSOLUTE value that 
provides the corresponding array dimension. 
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Switch Table Operation 


In the switch table operation, the CTIX system C compiler generates 
a compact set of instructions, determined by a special swbeg opera- 
tion, for the C language switch construct. For example, 


sub. | &1.%d0 
emp.! Ced0, &4 
bhi L421 
addw ©od0.%d0 
mov. Ww LO( “pe, %d0.w), %d0 
imp 6{ “pe, Ged0.w) 
swbey &5 
1.0722: 


short]. 15-L&%22 
shortl.Ce21-L.%22 
short!.Cr16-L.0722 
short].0721-1.%r22 
short]. 17-1622 


The special swbeg pseudo-operation communicates to the assembler 
that the lines following it contain rel-rel subtractions. Remember that 
ordinartly such subtractions are risky because of span-dependent 
optimization, Here, however, the assembler makes special al!owances 
for the subtraction because the compiler guarantees that both symbols 
will be defined in the current assembler file, and that one of the sym- 
bols is a fixed distance away from the current location. 


The swbeg pseudo-operation takes an argument that looks like an 
immediate operand. The argument is the number of lines that follow 
swbeg and that contain switch table entries. Swhbeg inserts two words 
into text. The first is the ILLEGAL instruction code. The second is 
the number of table entries that follow. The CTIX system disassem- 
bler needs the ILLEGAL instruction as a hint that what follows is a 
switch table. Otherwise it would get confused when it tried to decode 
the table entries (differences between two symbols) as instructions. 
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Span-Dependent Optimization 


The assembler makes certain choices about the object code it gen- 
erates based on the distance between an instruction and _ its 
operand(s). Choosing the smallest, fastest form is called span- 
dependent optimization. Span-dependent optimization occurs most 
obviously in the choice of object code for branches and jumps. It also 
occurs when an operand may be represented by the program counter 
relative address mode instead of an absolute two-word (long) address. 


The span-dependent optimization capability is normally enabled; the 
-n command line flag disables it. When this capability is disabled, 
the assembler makes worst-case assumptions about the types of object 
code that must be generated. 


The CTIX system compiler generates branch instructions without a 
specific offset size. When the optimizer is used, it identifies branches 
that could be represented by the short form, and it changes the opera- 
tion accordingly. The assembler only chooses between long and 
very-long representations for branches. 


Branch instructions, such as bra, bsr, and bgt, can have either a byte 
or a word pc-relative address operand. A byte size specification 
should be used only when the user is sure that the address intended 
can be represented in the byte allowed. The assembler will take one 
of these instructions with a byte size specification and generate the 
byte form of the instruction without asking questions. 


Although the largest offset specification allowed is a word, large pro- 
grams could conceivably have need for a branch to a location not 
reachable by a word displacement. Therefore, equivalent long forms 
of these instructions might be needed. When the assembler 
encounters a branch instruction without a size specification, or with a 
word size specification, it tries to choose between the long and very 
long forms of the instruction. If the operand can be represented in a 
word, then the word form of the instruction will be generated. Oth- 
erwise the very long form will be generated. For unconditional 
branches, e.g., br, bra, and bsr, the very long form is just the 
equivalent jump (jmp and jsr) with an absolute address operand 
(instead of pc-relative). For conditional branches, the equivalent very 
long form is a conditional branch around a jump, where the condi- 
tional test has been reversed. 


Table 15-1 summarizes span-dependent optimizations. The assembler 
chooses only between the long form and very long form, while the 
optimizer chooses between the short and long forms for branches (but 
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not bsr). 


TABLE 15-1 


ASSEMBLER SPAN-DEPENDENT OPTIMIZATIONS 


Instruction 


Short Form _ Long Form Very Long Form 


br, bra, bsr 


conditional 
branch 


imp, jsr 


lea.1, pea.1 


byte offset word offset jmp or jsr with absolute 
long address 


byte offset word offset short conditional branch 
with reversed condition 
around jmp with abso- 
lute long address 


pe-relative absolute long 
address address 


pe-relative absolute long 
address address 


Address Mode Syntax 


Table 15-2 summarizes the assembler syntax for the MC68K address- 
ing modes. The following notations are used in this table: 


represents any digit from 0 to 7. 


represent MC68K data or address registers. 


represents a displacement, and may stand for any abso- 
lute expression. 


stands for an absolute expression that represents a base 
displacement. 


stands for an absolute expression that represents an 
optional outer displacement. 


(as in %xn.S) stands for one of the operation size attri- 
bute letters b, w, or 1, representing a byte, word, or 
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long operation. 
scale (as in %xn.S*scale) represents a value of 2, 4, or 8. 


It is important to note that expressions used for the absolute address- 
ing modes need not be absolute expressions in the sense defined in 
“Types,” above. Although the addresses used in those addressing 
modes must eventually be filled in with constants, that can be done by 
the loader—there is no need for the assembler to compute them. The 
Absolute Long addressing mode is commonly used for accessing 
undefined external addresses. 
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TABLE 15-2 
EFFECTIVE ADDRESS MODES (Page 1 of 2) 


CTIX 
Motorola Assembler 
Syntax Syntax Effective Address Mode 
Dn Fodn Data Register Direct 
An ean Address Register Direct 
(An) (Yan) Address Register Indirect 
(An)+ (Yoan)+ Address Register Indirect with 
Postincrement 
-(An) -(%an) Address Register Indirect with 
Predecrement 
di,(AN) d(%an) Address Register Indirect 
( dyg,AN) with Displacement 


dg(An,Rn.W) 
dg(An, Rn.L) 


( dg,An,Xn. 
SIZE*SCALE) 


(bd,An,Xn. 
SIZE*SCALE) 


([bd,An],Xn. 
SIZE*SCALE, 
od) 


([bd,An,Xn. 
SIZE*SCALE] 
od) 


d(%an, %xn.w) 
d(%an, %xn.1) 


d(%an, %xn.S) 
bd(%an, 
9exn.S) 
od({bd, %an], 


9oxn.S*scale) 


od({bd, %an, 
%xn.S*scale]) 


(d signifies a signed 16-bit 
absolute displacement) 


Address Register Indirect 
with Index 


(d signifies a signed 8-bit 
absolute displacement) 


Address Register Indirect with 
Index (8-Bit Displacement) 


Address Register Indirect with 
Index (Base Displacement) 


Memory Indirect Post-Indexed 


Memory Indirect Pre-Indexed 


Address modes in boldface are for the MC68020 processor. 
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TABLE 15-2 


EFFECTIVE ADDRESS MODES (Page 2 of 2) 


Motorola Assembler Effective 

Notation Notation Address Mode 

xxx. W XXX Absolute Short Address 
(xxx signifies an expression 
yielding a 16- or 32-bit 
memory address) 

xxx.L XXX Absolute Long Address 
(xxx signifies an expression 
yielding a 32-bit memory 
address) 

LABEL(PC) d(%pce) Program Counter with 


LABEL(PC,Rn.W) 
LABEL(PC,Rn.L) 


(dg,PC,Xn. 
SIZE*SCALE) 


(bd,PC, Xn. 
SIZE*SCALE) 


([bd,PC],Xn. 
SIZE.SCALE,od) 


({bd,PC,Xn. 
SIZE*SCALE], 
od) 


#XXX 


d(%pe, %rn.w) 
d(%pe, Yorn.1) 


d(% pe, %xn.S) 


bd(% pe, % xn.) 


od([bd, % pe], 
%xn.S*scale) 


od([bd, % pe, 
%xn.S*scale 


&XXX 


Displacement 


(d signifies a signed 16-bit 
absolute displacement) 


Program Counter with Index 
(d signifies a signed 8-bit 
absolute displacement) 


Program Counter Indirect 
with Index (8-Bit 
Displacement) 


Program Counter Indirect 
with Index (Base 
Displacement) 


Program Counter Memory 
Indirect Post-Indexed 


Program Counter Memory 
Indrect Pre-Indexed 


Immediate Data 


(xxx signifies an absolute 
constant expression) 


Address modes in boldface are for the MC68020 processor. 
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Machine Instructions 


Table 15-3 shows how MC68K instructions should be written for the 
assembler. The following notations are used in this table: 


A (as in add.A) stands for one of the address operation size 
attribute letters w or I, representing a word or long opera- 
tion. 


S (as in add.S) stands for one of the operation size attribute 
letters b, w, or 1, representing a byte, word, or long opera- 
tion. 


FMT (as in fadd.FMT) stands for 


e one of the operation size attribute letters b, w, or I. 
representing a word or long operation. 


e one of the floating-point data format attribute letters s, 
d, x, or p, representing a single precision, double preci- 
sion, extended precision, or packed BCD operation. 


CC In the contexts bCC, dbCC, and sCC, the letters CC 
represent any of the following condition code designations 
(except that f and t may not be used in the bCC instruc- 


tion): 

cc carry clear 

cs carry set 

eq equal 

f false 

ge greater or equal 
gt greater than 

hi high 

hs high or same (=cc) 
le less or equal 

lo low (=cs) 

Is low or same 

It less than 

mi minus 

ne not equal 

pl plus 

t true 

ve overflow clear 
vs overflow set 


EA _ Represents an arbitrary effective address. 
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I An absolute expression, used as an immediate operand. 


Q Represents an absolute expression evaluating to a number 
from 1 to 8. 
L Represents a label reference, or any expression representing 


a memory address in the current section. 


The following represent registers: 


Toax Jodx Jofm 
Goay Jody Fn 
Yan %dn 


Refer to the notes under ‘meaning’ in Table 15-3 for additional 
information concerning registers not listed here. Refer to Appendix 
C of the MC68020 user manual for instruction formats and the hex 
values of operation codes. 


NOTE 


McC68020 instruction formats are in boldface. MC68881 
instruction formats begin with the letter f. 
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TABLE 15-3 


MC68K INSTRUCTION FORMATS (Page 1 of 17) 


Operation Assembler Syntax Meaning 

ABCD abcd.b Tody ,Jodx Add Decimal witn 
-(%ay),-(%ax) Extend 

ADD add.$ EA,%dn Add Binary 
%dn,EA 

ADDA add. A Ea,%an Add Address 

ADDI add.S &ILEA Add Immediate 

ADDQ add.S &Q,EA Add Quick 

ADDX addx.S Jody ,%eAx Add Extended 
(Gay) (eax) 

AND and.S EA,%dn AND Logical 
%dn,. EA 

ANDI and.$ &ILEA AND Immediate 

ANDI and.b &1,%cc AND Immediate to 

to CCR Condition Codes 

ANDI and.w &I1%sr AND Immediate to 

to SR the Status Register 

(Privileged Instruction) 

ASL asl.S Todx , Gedy Arithmetic Shift 

&Q,%dy (Left) 
asl.w &LEA 

ASR asr.S Todx ,Sedy Arithmetic Shift 

&Q.%dy (Right) 
asr.W &LEA 
Bee bCC L Branch Conditionally 


(16-bit Displacement) 


MC68020 instruction formats are in boldface. 


MC6SSS1 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 2 of 17) 


Operation Assembler Syntax Meaning 
bCC.b L Branch Conditionally 
(Short) (8-bit Displace- 
ment) 
BCHG bchg %dn,EA Test a Bit and Change 
&ILEA 


Note: bchg should be 
written with no suffix. 

If the second operand is 
a data register, .1 is 
assumed; otherwise .b is. 


BCLR belr %dn,EA Test a Bit and Clear 
&LEA 


Note: belr should be 
written with no suffix. 

If the second operand is 
a data register, .1 is 
assumed; otherwise .b is. 


BFCHG bfchg EA Test Bit Field and 
Change 

BFCLR bfcir EA Test Bit Field and 
Clear 

BFEXTS bfexts EA,%dn Extract Bit Field 
Signed 

BFEXTU bfextu EA,%dn Extract Bit Field 
Unsigned 

BFFFO bfffo EA, %dn Find First One in 
Bit Field 

BFINS bfins %dn,EA Insert Bit Field 

BFSET bfset EA Set Bit Field 


MC68020 instruction formats are in boldface. 
MC6S8S881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 3 of 17) 


Operation Assembler Syntax Meaning 
BFTST bftst EA Test Bit Field 
BKPT bkpt &I Breakpoint 
BRA bra L Branch Always 
(16-bit Displacement) 
bra.b L Branch Always (Short) 
(8-bit Displacement) 
br L Same as bra 
br.b L Same as bra.b 
BSET bset Yodn ,EA Test a Bit and Set 
&ILEA 


Note: bset should be 
written with no suffix. 

If the second operand is 
a data register, .1 is 
assumed; otherwise .b is. 


BSR bsr L Branch to Subroutine 
(16-bit Displace- 
ment) 

bsr.b L Branch to Subroutine 
(Short) (8-bit Displace- 
ment) 

BTST btst %dn EA Test a Bit and Set 

&I,EA 


Note: btst should be 
written with no suffix. 

If the second operand is 
a data register, .1 is 
assumed; otherwise .b is. 


CALLM callm &I,EA CALL Module 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 4 of 17) 


Operation Assembler Syntax Meaning 


CAS cas.S %dc, %duy,EA Compare and Swap 
with Operand 


Note: c represents com- 
pare; u represents update 
value. See MC68020 
User’s Manual for details. 


CAS2 cas2.A Godel: %dc2, Compare and Swap 
% dul: %du2, with Operand 
(%orn1:%rn2) 


Note: cl and c2 represent 
compare operands; ul and 
u2 represent update 
values; rnl and rn2 
represent effective 
addresses, See MC68020 
User’s Manual for details. 


CHK chk.w EA,%dn Check Register 
Against Bounds 
CHK2 chk2.S EA, %rn Check Register 
Against Bounds 
CLR elr.S EA Clear an Operand 
CMP cmp.S %odn ,EA Compare 
CMPA cmp.A Yan EA Compare Address 
CMPI cmp.S EA,&I Compare Immediate 
CMPM cmp.S (Yoax)+, Compare Memory 
(Yeay)+ 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 


MC68K INSTRUCTION FORMATS (Page 5 of 17) 


Operation Assembler Syntax Meaning 
Note: The order of 
operands in CTIX 
assembly language is the 
reverse of that in the 
MC68000 User’s 
Manual. 

CMP2 emp2.S Jorn,EA Compare Register 
Against Bounds 

DBee dbCC %dn,L Test Condition, Dec- 
rement and Branch 

dbra %dn,L. Decrement and 
Branch Always 
dbr %dn,L Same as dbra 
DIVS divs. w EA,%dn Signed Divide 
DIVSL divs.1 EA, %dq Signed Divide 
divs.1 EA, %dr: %dq 
divs. EA, %dr: %dq 
Note: r represents 
remainder; q represents 
quotient. 

DIVU divu.w EA,%dn Unsigned Divide 

DIVUL divu.l EA, %dq Unsigned Divide 

divu.! FA, %dr:%dq 

divul.1 EA, %dr: %dq 
Note: r represents 
remainder; q represents 
quotient. 

EOR eor.S %dn,EA Exclusive-OR Logical 


MC68020 instruction formats are in boldface. 


MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 6 of 17) 


Operation Assembler Syntax Meaning 

EORI eor.S &ILEA Exclusive-OR Immediate 
EORI eor.b &1,%cc Exclusive-OR Immediate 
to CCR to Condition Codes 
EORI eor.w &I1,%sr Exclusive-OR Immediate 
to SR to the Status Register 


(Privileged Instruction) 


ExG exg.] %orx, Wry Exchange Registers 
EXT ext.A %odn Sign Extend 
EXTB extb.1 %dn Sign Extend 
FABS fabs. FMT EA,%fn Absolute Value 
fabs.x %fim,%fn 
fabs.x %fn 
FACOS facos. FMT EA,%fn Arc Cosine 
facos.x %fm,%fn 
facos.x Jin 
FADD fadd. FMT EA,%fn Add 
fadd.x %fm,%fn 
FASIN fasin. FMT EA,%fn Arc Sine 
fasin.x %im,%fn 
fasin.x % fn 
FATAN fatan. FMT EA,%fn Arc Tangent 
fatan.x %fm,%fn 
fatan.x %fn 
FATANH fatanh. FMT EA,%fn Hyperbolic Arc 
fatanh.x %fm,%fn Tangent 
fatanh.x %fn 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 7 of 17) 


Operation Assembler Syntax Meaning 
FBec foCC.A L Branch Conditionally 
FCMP femp. FMT EA,%fn Compare 
femp.x %im,%fn 
FCOS feos. FMT EA,%fn Cosine 
foos.x %fm,%in 
fcos.x Fin 
FCOSIT fcosh. FMT EA,%fn Hyperbolic Cosine 
fcosh.x %im,%fn 
feosh.x %efn 
FDBec fdbCC %dn,L Test Condition, Dec- 


rement and Branch 


FDIV fdiv. FMT EA,%fn Divide 
fdiv.x % fm. %fn 

FETOX fetox. FMT EA,%fn (a 
fetox.x %fm,%fn 
fetox.x % fn 

FETOXM1 fetoxm!. FMT EA,%fn ex! 
fetoxm1.x %im,%fn 
fetoxm1.x %fn 

FGETEXP fgetexp. FMT EA,%fn Get Exponent 
fgetexp.x %fim,%fn 
fgetexp.x Jofn 

FGETMAN fgetman. FMT EA,%fn Get Mantissa 
fgetman.x %fm,%fn 
fgetman.x %fn 

FINT fint. FMT EA,%fn Integer Part 
fint.x %fim,%fn 
fint.x %fn 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 8 of 17) 


Operation Assembler Syntax Meaning 
FINTRZ fintrz. FMT EA,%fn Integer Part, Round- 
fintrz.x %im,%fn to-Zero 
fintrz.x %in 
FLOG10 flogl0. FMT EA,%fn Logis 
flog10.x % fm, %fn 
flog10.x %in 
FLOG2 flog2. FMT EA,%fn Log> 
flog2.x %fm,% fn 
flog2.x Jofn 
FLOGN flogn. FMT EA,%in Log. 
flogn.x %fm,%fn 
flogn.x fn 
FLOGNP1 flognp]. FMT EA,%fn Loge) 
flognp1.x Fim Join 
flognp1.x %fn 
FMOD fmod.FMT EA,%fn Modulo Remainder 
fmod.x % fm ,%fn 
FMOVE fmov. FMT EA,%fn Move Floating-Point 
fmov.FMT %fm,EA Data Register 
fmov.p %im,EAL{kK} 
fmov.p %fm,EAL{%dn} 
FMOVE fmov.] EA,%fper Move System Control 
fmov.1 %fper,EA Register 


Note: fp represents one 
of three control regis- 
ters. See MC68881 
User’s Manual for 
details. 


FMOVECR fmovecr.x &n,%in Move Constant ROM 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 9 of 17) 


Operation Assembler Syntax Meaning 


Note: nis offset. See 
MC68881 User’s Manual 


for details. 
FMOVEM fmovem.x &I,EA Move Multiple Data 
fmovem.x %dn,EA Registers 
fmovem.x EA,&I 
fmovem.x EA,%dn 
FMOVEM fmovem.1 &I,EA Move Multiple Con- 
fmovem.| EA,&I trol Registers 
Note: The immediate 
operand is a mask desig- 
nating which floating- 
point registers are to be 
moved to memory or 
which floating-point 
registers are to receive 
memory data. Not all 
addressing modes are 
permitted and the 
correspondence between 
mask bits and floating- 
point register numbers 
depends on the address- 
ing mode used. See 
MC68881 User's Manual 
for details. 
FMUL fmul. FMT EA,%fn Multiply 
fmul.x %fm,%fn 
FNEG fneg. FMT EA,%fn Negate 
fneg.x %fm,%fn 
fneg.x %fn 
FNOP fnop No Operation 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 10 of 17) 


Operation Assembler Syntax Meaning 

FREM frem. FMT EA,%fn IEEE Remainder 
frem.x %fm,%fn 

FRESTORE  frestore EA Restore Internal State 


(Privileged Instruction) 


FSAVE fsave EA Save Internal State 
(Privileged Instruction) 


FSCALE fscale. FMT EA,%fn Scale Exponent 
fscale.x %fm,%fn 

FSce foCC.b EA Set According to 

Condition 

FSGLDIV fsgidiv. FMT EA,%fn Single Precision Divide 
fsgldiv.x %{m,%fn 

FSGLMUL fsglmul. FMT EA,%fn Single Precision 
fsgimul.x %fm,%fn Multiply 

FSIN fsin. FMT EA,%fn Sine 
fsin.x %fim,%fn 
fsin.x %fn 

FSINCOS fsincos. FMT EA, %fce:%fs Simultaneous Sine 
fsincos.x Sim, Mfc: %fs and Cosine 


Note: s represents sine; 
n represents cosine. 


FSINH fsinh. FMT EA,%fn Hyperbolic Sine 
fsinh.x % fm ,%fn 
fsinh.x %ofn 

FSORT fsqrt. FMT EA,%fn Square Root 
fsqrt.x %fm,%fn 
fsqrt.x %in 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 11 of 17) 


Operation Assembler Syntax Meaning 
FSUB fsub. FMT EA,%fn Subtract 
fsub.x %fm,%fn 
FTAN ftan. FMT EA,%fn Tangent 
ftan.x %fm,%fn 
ftan.x %fn 
FTANH ftanh. FMT EA,%fn Hyperbolic Tangent 
ftanh.x %fm,%fn 
ftanh.x %fn 
FTENTOX ftentox. FMT EA,%fn 10* 
ftentox.x %im,%fn 
ftentox.x fn 
FTRAPPcc ftrappCC Trap Conditionally 
ftrappCC.w &l 
ftrappCC.1 &I 
FTST ftst. FMT EA Test Operand 
ftst.x %fm 
FTWOTOX ftwotox. FMT EA,%fn 2 
ftwotox.x %fm,%fn 
ftwotox.x %fn 
ILLEGAL illegal Take Illegal 
Instruction Trap 
JMP jmp EA Jump 
JSR jst EA Jump to Subroutine 
LEA lea.l EA,%an Load Effective Address 
LINK link.w Fan, &I Link and Allocate 
LINK link.! %an,&T Link and Allocate 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 


MC68K INSTRUCTION FORMATS (Page 12 of 17) 


Operation 


LSL 


LSR 


MOVE 


MOVE 
to CCR 


MOVE 

to SR 
MOVE 
from CCR 
MOVE 
from SR 


MOVE 
USP 


MOVEA 


MOVEC 


Assembler Syntax 


Isl.S 


\sl.w 


Isr.S 


Isr.w 


mov.S 


mov.w 


mov.Ww 


move.w 


mov.w 


mov.1 


mov.A 


movec.| 


%odx , ody 
&Q,%dy 


&I,EA 


%oadx, Jody 
&Q,%dy 


&ILEA 
EA,EA 


EA,%cc 


EA,%sr 


Jocc,EA 


%sr,EA 


Jousp, an 
%an,%usp 


EA,%an 


%cr,%rn 


Meaning 


Logical Shift (Left) 


Logical Shift (Right) 


Move Data from 
Source to Destination 


Note: If the destination 
is an address register, the 
instruction generated is 
MOVEA. 


Move to Condition 
Codes 


Move to the Status 
Register 
(Privileged Instruction) 


Move From the Con- 
dition Code Register 


Move from the Status 
Register 

(Privileged Instruction) 
Move User Stack Pointer 
(Privileged Instruction 

if Supervisor State) 


Move Address 


Move Control Register 


MC68020 instruction formats are in boldface. 


MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 


MC68K INSTRUCTION FORMATS (Page 13 of 17) 


Operation 


Assembler Syntax 


Meaning 


MOVEM 


MOVEP 


MOVEQ 


MOVES 


MULS 


MULS 


MULU 


movec.1 


movm.A 


movp.A 
mov.1 

moves.S 
moves.S 


muls.1 
muls.1 


muls.w 


mulu.w 


Jorn, %ocr 


&I,EA 
EA,&I 


%dx,D(%ay) 
&1,%dn 
%rn,EA 
EA,%rn 


FA, %dl 
EA, @dh: &dl 


EA,%dn 


EA,%dn 


(Privileged Instruction) 


Move Multiple 
Registers 


Note: The immediate 
operand is a mask desig- 
nating which registers 
are to be moved to 
memory or which regis- 
ters are to receive 
memory data. Not all 
addressing modes are 
permitted, and the 
correspondence between 
inask bits and register 
numbers depends on the 
addressing mode used. 
See MC68000 User’s 
Manual for details. 


Move Peripheral Data 


Move Quick (when I 
fits in one byte) 


Move Address Space 
(Privileged Instruction) 


Signed Multiply 


Note: h represents high 
order; | represents low 
order. 


Signed Multiply 


Unsigned Multiply 


MC68020 instruction formats are in boldface. 


MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 14 of 17) 


Operation Assembler Syntax Meaning 
MULU mulu.1 EA, &dl Unsigned Multiply 
mulu.) EA, %dh: %dl 


Note: h represents high 
order; | represents low 


order. 
NBCD nbcd.b EA Negate Decimal with 
Extend 

NEG neg.S EA Negate 
NEGX negx.S EA Negate with Extend 
NOP nop No Operation 
NOT not.S EA Logical Complement 
OR or.S EA, %dn Inclusive-OR Logical 

%dn,EA 
ORI or.S &I,EA Inclusive-OR Immediate 
ORI or.b &I,%cc Inclusive-OR Immediate 
to CCR to Condition Codes 
ORI or.w &I1,%sr Inclusive-OR Immediate 
to SR to the Status Register 

(Privileged Instruction) 

PACK pack -(%ax),-(%ay), Pack 

&number 

%dx, Fody, 

&number 
PEA pea.l EA Push Effective Address 
RESET reset Reset External Devices 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 15 of 17) 


Operation Assembler Syntax Meaning 


(Privileged Instruction) 


ROL rol.S Jodx, Tody Rotate without Extend 
&Q,%dy (Left) 
rol.w &I,EA 
ROR ror.S Jodx , Jody Rotate without Extend 
&Q,%dy (Right) 
ror.w &ILEA 
ROXL rox!.S Joax, Yody Rotate with Extend 
&Q, %dy (Left) 
roxl.w &I,EA 
ROXR roxr.S Jodx, Tody Rotate with Extend 
&Q,%dy (Right) 
TOXT.W &I,EA 
RTD rtd &number Return and Deallocate 
Parameters 
RTE rte Return from Exception 


(Privileged Instruction) 
RT™ rtm %rn Return from Module 


RTR rtr Return and Restore 
Condition Codes 


RTS rts Return from Subroutine 
SBCD sbcd.b Jody , Fodx Subtract Decimal with 
-(%ay) ,-(%ax) Extend 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 16 of 17) 


Operation Assembler Syntax Meaning 
Sec sCC.b EA Set According to 
Condition 
STOP stop &I Load Status Register 
and Stop 
(Privileged Instruction) 
SUB sub.S EA,%dn Subtract Binary 
%dn,EA 
SUBA sub.A EA,%an Subtract Address 
SUBI sub.S &LEA Subtract Immediate 
SUBQ sub.S &Q,EA Subtract Quick 
SUBX subx.S ody , Yodx Subtract with Extend 
-(%ay) -(%ax) 
SWAP swap.w %dn Swap Register Halves 
TAS tas.b EA Test and Set an Operand 
TRAP trap &l Trap 
TRAPcc trapCC Trap on Condition 
trapCC.w &I 
trapCC.l &I 
TRAPV trapv Trap on Overflow 
TST tst.S EA Test an Operand 
UNLK unlk Joan Unlink 
UNPK unpk -(%ax),-(%ay), Unpack Binary Coded 
&number Decimal 


MC68020 instruction formats are in boldface. 
MC68881 instruction formats begin with the letter f. 
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TABLE 15-3 
MC68K INSTRUCTION FORMATS (Page 17 of 17) 


Operation Assembler Syntax Meaning 
unpk %dx, Pedy, 
&number 


MC68020 instruction formats are in boldface. 
MC6888]1 instruction formats begin with the letter f. 
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Assembler Differences 


CTIX assembler coding differs from the coding conventions used in 
the MC68K user manuals in two ways. 


Comparison Instructions 


The CTIX assembler expects to see comparison operands in the 
reverse order of that presented in the MC68K user manuals. As an 
example, an MC68K instruction might look like 


CMP.W DS,D3 Is D3 less than D5? 
BLE IS_LESS Branch if less. 


The equivalent CTIX assembler instruction is 


cmp. Ww %d3,%d5 # Is d3 less than d5? 
ble is_less # Branch if less. 


The CTIX assembler follows the convention used by other assemblers 
supported in the UNIX system (both the 3B 20S computer and the 
VAX follow this convention). This convention makes for straightfor- 
ward reading of compare-and-branch instruction sequences. How- 
ever, it does lead to the peculiarity that if a compare instruction 1s 
replaced by a subtract instruction, the effect on the condition codes 
will be entirely different. This may be confusing to programmers 
who are used to thinking of a comparison as a subtraction whose 
result is not stored. Users of the assembler who become accustomed 
to the convention will find that both the compare and subtract nota- 
tions make sense in their respective contexts. 


Overloading of Opcodes 


The CTIX assembler permits operations which do more or less the 
same thing to be specified by a single assembly instruction. For 
example, the MC68K user manuals list the instructions SUB, SUBA, 
SUBI, and SUBQ, which all have the effect of subtracting their 
source operand from their destination operand. The CTIX assembler 
allows all these operations to be specified by the single assembly 
instruction sub. On the basis of the operands given to the sub 
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instruction, the CTIX assembler selects the appropriate MC68K 
operation code. 


Care must be taken when using this feature, since not all forms of 
such operations are semantically identical. For example, while SUB, 
SUBI, and SUBQ ll affect the condition codes in a consistent way, 
SUBA does not affect the condition codes at all. Consequently, the 
CTIX assembler user must be aware that when the destination of a 
sub instruction is an address register (which causes the sub to be 
mapped into the operation code for SUBA), the condition codes will 
not be affected. 
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Assembler. See CTIX assembly 


be 


language. 
B 


addition, 2-5 

arrays, 2-7 to 2-8, 2-19 

assignment statement, 2-10 

auto statement, 2-21 

automatic variables, 2-6 

base of input and output, 2-2, 
2-15 

break statement, 2-20 

C similarity, 2-2 

comments, 2-11, 2-13 

compound statement, 2-8, 2-19 

constants, 2-14, 2-16 

control statement, 2-8 to 2-9 

decimal places, 2-1, 2-15 

define functions, 2-6 

define statement, 2-21 

division, 2-2 

exponentiation, 2-2, 2-5, 2-17 

expression statement, 2-19 

for statement, 2-20 

functions, 2-6 to 2-7 

hexadecimal numbers, 2-4 

ibase variable, 2-3, 2-5 

identifiers, 2-13 to 2-14, 2-19 

if statement, 2-20 

keywords, 2-13 to 2-14 

leaving, 2-11 

math library, 2-11 

multiplication, 2-2 


Index 


named expressions, 2-14, 2-18 
obase variable, 2-3, 2-5 

quit statement, 2-21 

quoted string statements, 2-20 
relational operators, 2-18 
remainder, 2-5 

return statement, 2-6 to 2-7, 2-21 
scaling, 2-5 

sqrt function, 2-3 

storage classes, 2-19 
subscripted variable, 2-7 
subtraction, 2-2 

tokens, 2-13 

unary operators, 2-16 

while statement, 2-20 


Cc 


CTIX assembly language 


absolute type of expression, 15-11 
to 15-12, 15-20 to 15-21, 
15-23, 15-25 

address mode, 15-2, 15-19, 15-22 
to 15-23 

as command, 15-2 

attribute assigning operation, 
15-15 to 15-16, 15-20 

blank assembly code lines, 15-6 

bss section, 15-7, 15-13, 15-15 

byte operation, 15-11, 15-19, 
15-21, 15-24 

character constants, 15-5 

comment section, 15-14 

comments, 15-3 

comparison instructions, 15-43 

constants, 15-3 to 15-4 
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data initialization, 15-10 

data section, 15-7, 15-13 

decimal constant, 15-4 

division by zero, 15-9 

double floating point constant, 
15-4, 15-11 

effective address mode, 15-24 

evaluation of operators, 15-9 

expressions, 15-9 to 15-10 

flexname, 15-2 

floating point constant, 15-4, 15-9, 
15-11 

format of assembly language line, 
15-5 

g option, 15-15 

hexadecimal constant, 15-4 

ident pseudo-operation, 15-14 

identifiers, 15-3, 15-8, 15-10 

instruction formats, 15-26 

invoking the assembler, 15-2 

labels, 15-8 

location counter, 15-8 

location counter control, 
15-13 

long operation, 15-21, 15-24 

machine instruction, 15-24 

n command, 15-19 

numerical constants, 15-4 

octal constants, 15-4 

operators, 15-9 

ordinary character constants, 15-5 

overloading of opcodes, 15-43 

predefined registers, 15-3 

program sections, 15-6 

pseudo-operations, 15-2 to 15-3, 
15-6 to 15-7, 15-10, 15-15 to 
15-16, 15-18 

registers, 15-3 
15-25, 15-33 

relocatable type of expression, 
15-8 

section pseudo-operation, 15-14 
ifile, 15-14 

sections, 15-7 

span-dependent optimization, 
15-2, 15-10, 15-18 to 15-20 

special character constants, 15-5 

swbeg, 15-18 

swbeg, 15-18 

switch table, 15-18 

symbol definition, 15-10, 15-12 


15-10, 


to 15-4, 15-20, 


de 


symbolic debugging, 15-15 

syntax, 15-3, 15-20, 15-22 

text section, 15-7, 15-13, 15-15 

types, 15-8 

undefined external type of expres- 
sion, 15-8 

word operation, 15-21, 15-24 


D 


addition, 3-4, 3-6 

and BC language, 3-1 

commands, 3-1 to 3-2, 3-10 to 
3-11 

computations with integers, 3-1, 
3-6 

design choices, 3-11 

division, 3-7, 3-12 

dynamic string storage allocator, 
3-5 

exponentiation, 3-8, 3-12 

input conversion and base, 3-9 

internal arithmetic, 3-6 

internal registers and program- 
ming, 3-10 

numbers, 3-2 

output commands, 3-9 

output format and base, 3-9 

push-down registers and arrays, 
3-11 

remainder, 3-8 

square root, 3-8 

stack commands, 3-10 

subtraction, 3-6 


E 


eqn 


brackets, 12-13 

character sequences, 12-20 
displayed equations, 12-2 
example of, 12-18 
fractions, 12-7 

Greek letters, 12-20 
keywords, 12-19 

lining up, 12-12 

local motions, 12-18 
matrices, 12-15 
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piles, 12-14 

size and font changes, 12-9 
spacing, 12-3 to 12-5 
square roots, 12-8 
subscripts, 12-5 
superscripts, 12-5 
troubleshooting, 12-21 
usage, 12-22 

words recognized by, 12-21 


I 


Icc 


clients, 14-1 to 14-3, 14-5 to 14-6, 
14-9, 14-11 

control information, 14-6 

discarding a response, 14-21 

exchanges, 14-5, 14-10, 14-12, 
14-16, 14-22, 14-27 

message queues, 14-2, 14-5, 
14-16, 14-21 

obsolete messages, 14-23 

Pbcbs, 14-6 to 14-7 

random access to a message 
queue, 14-27 

request blocks, 14-5, 14-10 to 
14-11 
modified, 14-9 to 14-10 

request codes, 14-15 to 14-16 

request descriptor, 14-19, 14-23 

requests, 14-4 

response data, 14-8 to 14-9, 14-18 

response exchange, 14-7 

responses, 14-12, 14-18 

servers, 14-4, 14-15, 14-18 to 
14-19 

standard include file, 14-7, 14-12 


M 


arguments, 1-6 
arithmetic, 1-2, 1-7 

basic operations, 1-2 
built-in macros, 1-2 to 1-3 
conditionals, 1-9 

defining macros, 1-3 
features, 1-1 

file manipulation, 1-8 
printing, 1-11 

quoting, 1-4 


summary of built-ins, 1-12 
system command, 1-9 
usage, 1-2 


displays, 11-7, 11-9 

double spacing, 11-5 
footnotes, 11-11 

headers and footers, 11-4 
indented paragraphs, 11-14 
indenting, 11-5 

indexes, 11-13 

keeps, 11-8 

lists, 11-8 

paragraphs, 11-3 
paragraphs, indented, 11-14 
quotes, 11-7 

section headings, 11-17 
spacing, 11-5 

underlining, 11-7 

usage, 11-1 


mm 


abstracts, 9-43 
accents, 9-83 
authors, 9-42 
captions, 9-59 
cover sheets, 9-74 
displays, 9-52 to 9-54 
equations, 9-58 
errors and debugging, 9-84, 9-100, 
9-103 
examples 
footnotes, 9-61, 9-95 
letters, 9-97 
lists, 9-30, 9-36, 9-92 
lists with hanging indents, 9-88 
page headers and footers, 9-67 
fonts, changing of, 9-76 
footnotes, 9-60 to 9-63 
format changing, 9-46 
formatting concepts, 9-2, 9-12, 
9-17 
headings, 9-17, 9-19 to 9-27 
for two-column output, 9-80 
hyphenation, 9-14 
listing figures and tables, 9-60 
lists, 9-30, 9-32 to 9-36, 9-38 
macros, summary of, 9-105 
memorandums, 9-40, 9-43 to 9-44 
9-49 


+ 
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ms 


modifying macros, 9-86 

number registers, 9-9 

number registers, summary of, 
9-111 

page headers and footers, 9-63 to 
9-67 

page numbering, 9-26 

paragraphs, 9-17 

point size, 9-82 

references, 9-74 to 9-75 

released-paper style, 9-47 

strings, summary of, 9-110 

table of contents, 9-26, 9-71 

tables, 9-56 

titles, 9-41 

two-column output, 9-79 to 9-80 

usage, 9-5, 9-7 to 9-8 

vertical spacing, 9-80, 9-82 


accents, 10-12 

boxing words or lines, 10-10 

changeable registers, 10-12, 10-27 

commands, summary of, 10-11, 
10-15 

cover sheets and first pages, 10-3 

dating, 10-11 

displays, 10-9, 10-23 

document typing, 10-1 to 10-4, 
10-11, 10-13 
beginning, 10-2 

double columns, 10-4, 10-25 

equations, 10-13, 10-26 

examples, 10-17 

footnotes, 10-9, 10-23 

headings, 10-3 to 10-4, 10-22 

indented paragraphs, 10-6 

keeping blocks together, 10-10 

keeps, 10-25 

lists, 10-7, 10-22 

mathematics, 10-13 

memos, prepartion of, 10-17, 
10-21 

multi-column formats, 10-4 

multiple indents, 10-7, 10-24 

nroff/troff commands, 10-11 

page headings, 10-3 

Paragraph indents, 10-6 

references for further study, 10-13 

register names, 10-15 

signature line, 10-11 

tables, 10-9, 10-28 


underlining, 10-8 
usage, 10-29 


N 


nroff/troff 


applications, 7-1 

arguments, 7-29 to 7-30 

character set, 7-61 to 7-63 

commands, summary of, 7-5, 7-12 

comments, 7-40 to 7-41 

conditionals, 7-10, 7-47 to 7-48 

control characters, 7-39 to 7-40 

diversions, 7-7, 7-30 to 7-31 

environment switching, 7-11, 7-49 
to 7-50 

error messages, 7-52 to 7-53 

escape sequences, 7-13 

examples, 7-52 to 7-53 
footnotes, 7-57 to 7-58 
last page, 7-60 to 7-61 
multiple columns, 7-57 to 7-58 
page margins, 7-53 to 7-54 
paragraphs and headings, 7-55 

to 7-56 

fields, 7-36 to 7-37 

file switching, 7-11, 7-50 to 7-51 

font and character size control, 
7-5, 7-18 

fonts, 7-18 to 7-19, 7-61 to 7-62 

formatting documents, 7-15 to 
7-16 

hyphenation, 7-9, 7-44 to 7-45 

input character translations, 7-37 
to 7-38 

input/output conventions, 7-9 

insertions, 7-11, 7-49 to 7-50 

ligatures, 7-37 to 7-38 

line drawing, 7-43 to 7-44 

line length and indenting, 7-7, 
7-27 to 7-28 

line numbering, 7-10, 7-46 to 7-47 

line-spacing, 7-26 to 7-27 

local motions, 7-40 to 7-41 

macros and strings, 7-7, 7-28 to 
7-29 

marking horizontal place, 7-42 to 
7-43 

number registers, 7-8, 7-14, 7-33 
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to 7-34 

options and effects, 7-2 

overstriking, 7-38 to 7-39, 7-42 to 
7-43 

page control, 7-5, 7-21 

point size, 7-19 

requests, summary of, 7-5, 7-12 

tabs, 7-8, 7-35 to 7-36 

text filling and adjusting, 7-6, 7-23 
to 7-24 

titles, 7-10, 7-45 to 7-46 

traps, 7-7, 7-31 to 7-32 

underlining, 7-38 to 7-39 

usage, 7-2 

vertical spacing, 7-6, 7-25 to 7-27 

width function, 7-41 to 7-42 

zero-width characters, 7-42 to 
7-43 


addresses, 6-4 
appending lines, 6-8 
command format, 6-3 
deleting lines, 6-7 
flow-of-control 
6-16 
functions, 6-7, 6-10, 6-12, 6-14 
hold and get functions, 6-14 
input/output functions, 6-12 
multiple input-line functions, 6-14 
order of application of editing 
commands, 6-3 
pattern space, 6-3 
regular expressions, 6-2, 6-5 
selecting lines for editing, 6-4 
substitution within lines, 6-10 
terminate execution, 6-17 
usage, 6-2 
writing to a file, 6-11 to 6-12 


functions, 6-3, 


T 


column width, determining, 13-7 

command characters, summary of, 
13-26 

data, 13-8 

default parameters, 13-8 

examples, 13-13 


font changes, 13-7 

formatting, 13-4 

horizontal lines, 13-6, 13-9 

input commands, 13-3 

input format, 13-2 

options, 13-3 

point size changes, 13-7 

spacing between columns, 13-6 

text blocks, 13-9 

troff commands 
13-8 

usage, 13-11 

use with eqn, 13-11 

vertical lines, 13-6 

vertical spacing, 13-7 

vertical spanning, 13-6, 13-9 


within tables, 


troff 


vi 


character set, 8-31 
conditionals, 8-26 
diversions, 8-28 
environments, 8-27 

fonts, 8-6 

line drawing, 8-11 

line length and indenting, 8-9 
local motions, 8-11 

macros, 8-16 

macros with arguments, 8-23 
number registers, 8-21 

page numbering, 8-18 

point sizes, 8-4 

special characters, 8-6 
strings, 8-15 

tabs, 8-10 

titles, 8-18 

usage, 8-2 

vertical spacing, 8-4 


Vv 


abbreviations, 4-29 

appending text, 4-11, 4-15, 4-35 

arrow keys, 4-4 

backing up in input mode, 4-12 

character functions, 4-38 

commands, summary of, 4-10, 
4-14, 4-18, 4-32, 4-34, 4-38, 
5-5 

control characters, 4-16, 4-35 
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corrections, 4-12 to 4-13 
undoing, 4-14 
counts, 4-31 
deleting text, 4-13, 5-10 
duplicating text, 4-15, 4-17 to 
4-18 
editing files, 4-3, 4-19, 5-4 
editing LISP programs, 4-27 
editing on slow terminals, 4-21 
ESC key, 4-5 
escaping to shell, 4-19 
ex, 4-36, 5-16 
exiting files, 4-6, 4-19, 5-4 
insert characters, 5-15 
inserting text, 4-11, 4-15, 5-10 
macros, 4-28 
marking and returning, 4-20 
moving around on the screen, 4-8 
moving text, 4-15, 4-17, 5-11 
moving within a line, 4-9 
recovering lost files, 4-25 
recovering lost text, 4-24 
replacing text, 5-11 
scrolling and paging, 4-6, 5-5 
searches, 4-7, 4-33, 5-9 
set commands, 4-22, 5-18 
setting options, 4-22 
terminals 
selecting of, 5-3 
specifying type, 4-2 
upper case only, 4-36 
undoing changes, 4-14 
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